goba Wed Jun 18 14:10:12 2003 EDT
Modified files:
/phpdoc/RFC 2003_meeting_agenda.html
Log:
- Soften the "contact Goba" links a bit
- Update meeting time info, it will surely be on July 10,
but when and where is still unkown
- Grammar fixing in many places
- Adding more info on livedocs
Index: phpdoc/RFC/2003_meeting_agenda.html
diff -u phpdoc/RFC/2003_meeting_agenda.html:1.10
phpdoc/RFC/2003_meeting_agenda.html:1.11
--- phpdoc/RFC/2003_meeting_agenda.html:1.10 Mon Jun 16 17:06:08 2003
+++ phpdoc/RFC/2003_meeting_agenda.html Wed Jun 18 14:10:12 2003
@@ -68,7 +68,7 @@
<div class="content">
<h1>PHP Documentation Meeting 2003 - Agenda</h1>
- <p class="cvsid">$Id: 2003_meeting_agenda.html,v 1.10 2003/06/16 21:06:08
goba Exp $</p>
+ <p class="cvsid">$Id: 2003_meeting_agenda.html,v 1.11 2003/06/18 18:10:12
goba Exp $</p>
<p>Members of the PHP Documentation Team <a title="meeting protocol"
href="http://www.php-ev.de/documents/phpdoc/protocol.html";>met in 2002
@@ -80,12 +80,10 @@
<p>The meeting will take advantage of <a title="English LinuxTag site"
href="http://www.linuxtag.org/2003/en/index.html";>LinuxTag</a> which
- will take place in Karlsruhe, between 2003. July 10 and 13. <strong>It
- seems now that the meeting will be on July 10, further info will be available
- later</strong>. If you have any problems with the date, please
- <a href="#contact">write to Goba</a> [it is probably not a
- good idea to start a new public discussion on this for every single
- person].</p>
+ will take place in Karlsruhe, between 2003. July 10 and 13. <strong>The
+ meeting will be on July 10, and will be a whole day event if possible,
+ starting the morning.</strong> Exact place and start time is not known
+ yet.</p>
<p>
Here is a list of those who are currently known to be at Linuxtag, and
@@ -113,8 +111,8 @@
<li>Zic, <strong>Sandro</strong></li>
</ul>
<p>If you have any problems with this list [you are on it, but will
- not be there, or the other way round] then <a href="#contact">contact
- Goba</a></p>
+ not be there, or the other way round] then fix the list in phpdoc
+ CVS, or <a href="#contact">contact Goba</a></p>
<p>This summary was created in the hope that it will be useful, and would
help better use the very few available hours to discuss the topics. Note
@@ -128,7 +126,8 @@
on it at <a href="#contact">phpdoc</a>. For topics described here, see the
pointed articles, RFCs, proposals, discussions, and see if you can say new
or can sum up the discussions better. In case you have pointers to more info
- on some topics, please <a href="#contact">contact Goba</a></p>
+ on some topics, add those to the page in phpdoc CVS, or
+ <a href="#contact">contact Goba</a></p>
<ol>
<li>
@@ -144,10 +143,11 @@
At the 2002 meeting we found that we need one or a few license
guys, who can handle license questions, so there won't be a need
to contact all listed authors / editors in case of a license
- related request. Who should those be, was not decided yet.</p>
+ related request. Who should those be, was not decided yet, Goba
+ was proposed.</p>
<p>There were no guidelines provided however on how to give credit
to contributors and this is still an open question. There were
- some threads on this at phpdoc. It seems to me, that initial human
+ some threads on this at phpdoc. It seems, that initial human
based nominations were accepted and agreed, but there was no agreement
regarding mass listing of smaller contributors.</p>
@@ -156,7 +156,8 @@
<ul>
<li>One list or a "main" and an "others" list?</li>
<li>Human based inclusion or machine based?</li>
- <li>Who should decide on license questions?</li>
+ <li>Who should decide on license questions (including
+ translations)?</li>
<li>What to do with the inactive contributors?</li>
<li>What names/titles exist for those that contribute?
Helper, Author, Editor, Technical Editor, etc.
@@ -194,13 +195,13 @@
<div class="points">
Some important questions:
<ul>
- <li>How to intagrate such stuff into the current system?</li>
+ <li>How to integrate such stuff into the current system?</li>
<li>Authorize the submissions before committing?</li>
<li>What impact would a WYSIWYG editing method has on
our diffing+mailing system, as WYSIWYG editors are known
- to 'rewrite' files, and produce useless diffs</li>
+ to 'rewrite' files, and produce useless diffs?</li>
<li>Where will the required diff -u and make test commands
- be executed? People really need to check these before
+ be executed? People really need to check these before
any commit is done and we don't have the resources to
execute these for everyone (or do we?)</li>
</ul>
@@ -217,9 +218,9 @@
<h3>Handling user notes</h3>
<p>We have a very few volunteers working on the manual user notes
- now. This is somewhat because of the fact that those guys are not
- recognized at all, the php-notes list is even not widely known to
- exist. Still those who work there do a good job in keeping the
+ now. This low number is somewhat because of the fact that those guys
+ are not recognized at all, the php-notes list is even not widely known
+ to exist. Still those who work there do a good job in keeping the
notes somewhat clean and integrating useful content into the
manual.</p>
<p>There were some ideas on improving this system, including the
@@ -230,10 +231,10 @@
request it, and in what form [eg. without email addresses to prevent
further mass email harvesting].</p>
- <p>Long ago there was discussed (and even commited code) about a
system
+ <p>Long ago there was discussion (and even commited code) about a
system
that allows people (anyone, with or without CVS accounts) to
"maintain"
- a manual pages notes. For example, Joe would manage the strlen()
- notes. Not to say only Joe could edit them but Joe would at least
focus
+ a manual page's notes. For example, Joe would manage the strlen()
+ notes. Not to say only Joe could edit them but Joe would at least
focus
on this page and/or other pages.</p>
<div class="seealso">
@@ -267,7 +268,7 @@
so building the manuals is a heavy task</li>
</ul>
- <p>Let me explain the building process of building the manual, so
+ <p>Let me explain the process of building the manual, so
you can see the problems, even if you are not working for the
docteam every day. <span class="redlines">Red lines</span> mark
this explanation, so in case you are not that interested, you know
@@ -308,7 +309,7 @@
here, which uses [o]nsgmls to find errors. Similar to this is
<tt>make test_man_gen</tt> which is run on the build server, and
it is more forgiving for link endpoint errors, in case there are
- any left after the above configure run</li>
+ any left after the above configure run.</li>
<li>
In case you would like to get HTML output, you can run
@@ -340,14 +341,14 @@
<li>
The PalmDoc version [<tt>make palmdoc</tt>] depends on a txt
version already built [which is done with filtering the bightml
output
- through lynx]. This targer runs the <tt>scripts/makedoc</tt>
+ through lynx]. This target runs the <tt>scripts/makedoc</tt>
program to create the isilo version out of the txt [compresses
the text file].
</li>
<li>
- The Palm iSilo version [<tt>make isilo</tt>] uses iSilo386
external
- program which should be installed on the build machine. It
+ The Palm iSilo version [<tt>make isilo</tt>] uses the iSilo386
+ external program which should be installed on the build machine.
It
compresses the bightml version using the iSilo format.
</li>
@@ -405,18 +406,21 @@
entities and untranslated documents, though there are proposed
solutions
for that.</p>
- <p>I [Goba] had a suggestion on the XSLT base to build a TOC first and
+ <p>Goba had a suggestion on the XSLT base to build a TOC first and
then skip non-translated parts on the XSLT level. That would enable
- quick testing too. Wez has a "livedocs" idea which may lead to a more
- maintainable solution then XSLT, but we have very small amount of info
- on it currently.</p>
+ quick testing too. Wez has a "livedocs" concept which may lead to a
+ more maintainable solution then XSLT. Ongoing work on that shows that
+ it can quickly become a useable solution for all of the HTML formats.
+ Damien also uses a similar solution to parse DocBook XML with PHP
+ to create the special French versions of the manual, including the
+ PDF [filtering HTML though the htmldoc PDF generator].</p>
<p>Regarding the offline versions of the manual, Goba had an idea of
a "self-hosted manual" which would provide integration support for
PEAR,
PHP-GTK and any other docs, and would use XML for navigation and HTML
and/or XML for formatted pages. Local searching would be supported
with a
PHP based solution. Even customized PDF building would be possible
with
- this version.</p>
+ this version. Wez's livedocs will be the base of this for the PHP
docs.</p>
<div class="points">
Some important questions:
@@ -440,13 +444,17 @@
livedocs suggestion</a>, <a
href="http://marc.theaimsgroup.com/?l=phpdoc&m=105251292424018";>Goba's
self hosted docs RFC</a>, <a
href="http://marc.theaimsgroup.com/?l=phpdoc&m=105101187801978";>one speedup idea from
Goba</a>,
<a
href="http://marc.theaimsgroup.com/?l=phpdoc&m=105136521804028";>another speedup idea
from Goba</a> and the <a
href="http://marc.theaimsgroup.com/?l=phpdoc&m=105308195019732";>discussion
- on the Hebrew encoding issue and RTL problems</a>
+ on the Hebrew encoding issue and RTL problems</a>. Damien's French
+ docs are available from
+ <a href="http://dev.nexen.net/docs/php/index.php";>Nexen.net</a>.
+ The tool he uses for PDF generation is
+ <a href="http://www.easysw.com/htmldoc/index.html";>htmldoc</a>.
</div>
</li>
<li>
<h3>Structuring the documentation</h3>
- <p>Having structure see also sections in the documentation,
+ <p>Having structured see also sections in the documentation,
grouping of reference sections by type and manpage like function
documentation are old ideas. The problem with most of these ideas
is that the current DSSSL based build system blocks us from going
@@ -471,6 +479,9 @@
<ul>
<li>Is it OK to use a modified DocBook DTD?</li>
<li>Is the manpage like function documentation still
preferred?</li>
+ <li>What is higher priority in the above suggestion list
+ (reference grouping, structured see alsos, manpage
+ structure)?</li>
</ul>
</div>
@@ -478,7 +489,7 @@
See also: <a
href="http://cvs.php.net/co.php/phpdoc/RFC/reference_grouping";>RFC/reference_grouping</a>,
<a
href="http://cvs.php.net/co.php/phpdoc/RFC/manual.xml.in";>RFC/manual.xml.in</a>,
and <a
href="http://cvs.php.net/co.php/phpdoc/dtds/phpbook.dtd";>dtds/phpbook.dtd</a>
- which has add support for reference grouping to DocBook XML
+ which has add support for reference grouping to DocBook XML.
</div>
</li>
<li>
@@ -489,10 +500,10 @@
PHP classes using DocBook. It is important that when PHP 5 comes
out [even in RCs?], the documentation should be up to date. But
it is also important that we are not placing content into the manual
- related to PHP 5 without special notices.</p>
+ related to PHP 5 without special notices, so users won't get
confused.</p>
<p>With the upcoming PHP releases and with PHP 5, many extension will
- be moved [is already moved] to PECL. The PHP documentation is getting
+ be moved [some are already moved] to PECL. The PHP documentation is
getting
increasingly ready for a copy-paste move of the docs of those
extensions
[having all extension related docs at one place]. But it is still not
decided whether all moved extensions' docs should move to PECL docs,
@@ -501,7 +512,7 @@
<p>It is also important to maintain some consistency in moved docs.
Eg. have a listing of removed extensions, make the URL shortcuts
redirect to the PECL manual, move / remove the user notes related
- to those extensions, etc. Also, before anything is officially moved
+ to those extensions, etc. Also, before anything is officially moved
out of phpdoc, it should be available online in the peardoc
manual.</p>
<div class="points">
@@ -510,7 +521,7 @@
<li>How / when to document PHP 5 features?</li>
<li>What extensions will be moved to PECL and when?</li>
<li>Is it true that every extension will be moved into PECL,
but most still bundled?</li>
- <li>Will peardoc/PECL continue to use our old extension.xml
format? This makes moving more difficult.</li>
+ <li>Will peardoc/PECL continue to use our old extension.xml
format? This makes moving more difficult.</li>
</ul>
</div>
@@ -522,15 +533,15 @@
</div>
</li>
<li>
- <h3>What do do with PHP3 documentation</h3>
+ <h3>What do do with PHP 3 documentation</h3>
- <p>In an effort to preserve history and possible PHP3 users, we need
+ <p>In an effort to preserve history and possible PHP 3 users, we need
to keep this information available but at the same time it adds
- clutter to the documentation. One proposal is to list all PHP3
- information in its own appendix, and add appropriate links/notes
- to them. Within a manual page, one will see a simple link titled
- "PHP3 Note" and it'll link to the appropriate location in the "PHP3
- Appendix". In here it might mention a feature was added in PHP3, etc.
+ clutter to the documentation. One proposal is to list all PHP 3
+ information in it's own appendix, and add appropriate links/notes
+ to them. Within a manual page, one will see a simple link titled
+ "PHP 3 Note" and it'll link to the appropriate location in the "PHP 3
+ Appendix". In here it might mention a feature was added in PHP 3, etc.
Most people seemed to like this idea, no specifics have been
discussed.</p>
<div class="seealso">
@@ -544,8 +555,9 @@
presentation of the online and offline manuals. Manual search
solutions, PHP source code highlighting, better table of
contents, indexes and other stuff would greatly add to the user
- experience. Also, one should be able to search both peardoc
- and phpdoc manuals through one interface (ex. php.net/sqlite)</p>
+ experience. As PEAR is becoming more important, peardoc items
+ may need quick access from php.net, using URL shortcuts and
+ searches (eg. php.net/sqlite).</p>
<p>The extended CHM is the best version for onscreen browsing
on Windows. We should build on it's experience and add new
@@ -554,7 +566,7 @@
<p>The role of the different formats should also be discussed.
Whether we need two different Palm versions, two different CHM
- versions and the if anyone uses the bightml version [except for
+ versions and if anyone uses the bightml version [except for
converting it to PDF]? Would a self-hosted manual obsolote the
CHMs?</p>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
