goba Sat May 31 07:19:46 2003 EDT
Added files:
/phpdoc/RFC 2003_meeting_agenda.html
Log:
Adding first version of the 2003 phpdoc meeting agenda.
Please don't fix the whitespace and discuss every major
modification
Index: phpdoc/RFC/2003_meeting_agenda.html
+++ phpdoc/RFC/2003_meeting_agenda.html
<!-- Please don't apply any whitespace changes or reformatting to this file,
I would like to see clear diffed changes in case you modify anything,
Goba -->
<html>
<head>
<title>PHP Documentation Meeting 2003 - Agenda</title>
<style>
body, html {
background-color: #666699;
margin: 0px;
padding: 0px;
}
.content {
font-family: verdana, arial, sans-serif;
background-color: white;
width: 70%;
margin: auto;
border-style: solid;
border-color: #9999cc;
border-width: 0px 7px 0px 7px;
padding: 10px;
}
h1 {
border-bottom: 1px solid black;
}
h2 {
border-bottom: 1px dashed black;
}
a, a:hover, a:visited, a:active, .linklooking {
color: navy;
text-decoration: underline;
}
.seealso, .points {
background-color: lightyellow;
padding: 3px;
border-style: dotted;
border-width: 0px 0px 1px 1px;
margin-bottom: 5px;
}
.points {
background-color: #f5f5f5;
}
ul li {
list-style-type: square;
margin-bottom: 2px;
}
ul {
margin-bottom: 5px;
margin-top: 5px;
}
.buildsys {
border-style: dashed;
border-width: 0px 2px 0px 2px;
border-color: red;
padding: 0px 5px 0px 5px;
}
.redlines {
border-style: dashed;
border-width: 0px 1px 0px 1px;
border-color: red;
}
.cvsid {
color: darkgray;
}
</style>
</head>
<body>
<div class="content">
<h1>PHP Documentation Meeting 2003 - Agenda</h1>
<p class="cvsid">$Id: 2003_meeting_agenda.html,v 1.1 2003/05/31 11:19:46 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
in Stuttgart</a> to discuss several problems of the PHP documentation
and find ways to improve the content, the technical background, the
communication, the legal issues, etc. Now it is 2003 and time has come
to organize another face-to-face meeting to discuss what has to be done
to achive those goals not reached yet, and to define new ones.</p>
<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>
<p>
Here is a list of those who are currently known to be at Linuxtag, and
probably interested in the meeting [in alphabetical order, without
accents]:</p>
<ul>
<li>Arntzen, <strong>Thies</strong> C.</li>
<li>Bergmann, <strong>Sebastian</strong></li>
<li>Betz, <strong>Friedhelm</strong></li>
<li>Boerger, <strong>Marcus</strong></li>
<li>Fox, <strong>Steph</strong></li>
<li>Furlong, <strong>Wez</strong></li>
<li>Greant, <strong>Zak</strong> [maybe]</li>
<li>Hartmann, <strong>Johann-Peter</strong></li>
<li>Hojtsy, <strong>Gabor</strong> [aka Goba]</li>
<li>Holzgraefe, <strong>Hartmut</strong></li>
<li>Kronsbein, <strong>Mark</strong></li>
<li>Lerdorf, <strong>Rasmus</strong></li>
<li>Rethans, <strong>Derick</strong></li>
<li>Richter, <strong>Georg</strong> [maybe only partial]</li>
<li>Schroder, <strong>Kai</strong></li>
<li>Schumann, <strong>Sascha</strong></li>
<li>Weinert, <strong>Thomas</strong></li>
<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>
<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
that in 2002 we had a multiday event, while this is not possible now as
it seems, but we still have plenty to discuss.</p>
<a name="topics"></a>
<h2>Topics for discussion</h2>
<p>If you have a new topic for discussion, feel free to open a new thread
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>
<ol>
<li>
<h3>Crediting manual contributors</h3>
<p>This problem is in the air for a long time now. We have no
rules now on who can be listed as an author / editor. This was
decided by the editors in the past after community discussion
on a case by case basis. The current license legally puts the
manual under the hands of those listed on the frontpage, though
there are much more contributors who helped with adding content,
finetuning the build system, etc.</p>
<p>There were several suggestions on improving the situation.
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>
<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
based nominations were accepted and agreed, but there was no agreement
regarding mass listing of smaller contributors.</p>
<div class="points">
Some important questions:
<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>What to do with the inactive contributors?</li>
</ul>
</div>
<div class="seealso">
See also:
<a
href="http://marc.theaimsgroup.com/?l=phpdoc&m=105188580930824";>The
"finally: new authors" thread started with this letter</a> and
<a
href="http://marc.theaimsgroup.com/?l=phpdoc&m=105198711005958";>The
"list of contributors [rethought]" thread started with this
letter</a>
</div>
</li>
<li>
<h3>A user friendly translation / editing environment</h3>
<p>The PHP documentation has many translations, some of them
are halted, near dead projects. The main problem with them is
probably that the joining requirements are too high [Linux / cygwin,
CVS, XML]. Or at least they seem too high for regular PHP programmers,
who would be happy to help. It would also be convinient many times
for experienced helpers to just concentrate on the content, and
not bother with XML.</p>
<p>Sandro Zic as well as others have many good ideas on integrating
some WYSIWYG editors [optinally] into the workflow, so we can get
more contributors to translate, and fix documentation. A convinient
system is also needed to easily update what is translated, as left
alone old translations are sometimes much worse then non-translated
content.</p>
<div class="points">
Some important questions:
<ul>
<li>How to intagrate 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>
</ul>
</div>
<div class="seealso">
See also: <a
href="http://marc.theaimsgroup.com/?l=phpdoc&m=104637138832462";>Sandro's proposal</a>,
the <a href="http://www.bitfluxeditor.org/";>Bitflux Editor</a> and
a paper on <a href="http://www.zzoss.com/projects/oowdbk/";>DocBook
Editing with OpenOffice.org</a>
</div>
</li>
<li>
<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
notes somewhat clean and integrating useful content into the
manual.</p>
<p>There were some ideas on improving this system, including the
adoption of the voting system used on the PHP-GTK site, an approval
system for the user notes, and having extensions dedicated to
given user note maintainers. Another good question is whether
we will supply the user notes with the offline formats as users
request it, and in what form [eg. without email addresses to prevent
further mass email harvesting].</p>
<div class="seealso">
See also: <a href="http://gtk.php.net/manual/en/";>the PHP-GTK
manual</a> for some ideas on how the rating works there, and
the <a
href="http://www.php-ev.de/documents/phpdoc/protocol.html";>2002
meeting protocol</a> on the user note related findings there.
</div>
</li>
<li>
<a name="buildsys"></a>
<h3>Build system [aka getting rid of DSSSL]</h3>
<p>The build system is the foundation of our documentation
framework. There are several problems with it, depending on
from where are you looking at it.</p>
<ul>
<li>Getting to know the build system is hard for newcomers
[especially coming from the Windows world].</li>
<li>Maintaining the build system is not easy, we don't have
expertise to customize the DSSSL stylesheets, which is
one of the building blocks of the system, this stops
many advances [see also parts, reference grouping]</li>
<li>Getting some results out of the build system takes a
very long time, and so it is not useable for quick
translation testing.</li>
<li>Due to the previous point the builds take days for all the
languages on the building server on 100% processor load,
so building the manuals is a heavy task</li>
</ul>
<p>Let me explain the building 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
what to skip :) I know that this may be boring, but the quality
of the translations and the manual is largely depends on the build
system, so it is a very important issue [eg. PDF or extended CHM
building].</p>
<div class="buildsys">
<p>For a working build system, one needs the usual
Linux tools [cvs, autoconf, make, gcc for some operations], plus
a PHP CLI or CGI setup and [open]jade with [o]nsgmls. To build
some format of the manual you need to do:</p>
<ul>
<li><tt>cvs checkout phpdoc</tt></li>
<li><tt>cd phpdoc</tt></li>
<li><tt>cvs chechout phpdoc-LANG-dir</tt>, replacing LANG
with the desired language, repeating this for all the
languages needed [except English]</li>
<li><tt>autoconf</tt> - this will create ./configure</li>
<li>
<tt>./configure --with-lang=LANG</tt><br>
This will do some preparations:
<ul>
<li>search for tools [jade, openjade, PHP, etc.]</li>
<li>replace configuration vars in all the files ending in
".in"</li>
<li>create file entities for all the XML files used</li>
<li>run [o]nsgmls to create a list of entities and link
endpoints
referenced, but not available in the document to make
the build
process work even if such errors exist</li>
</ul>
After this, the build system is configured, and you can
choose a format to build the manual.
</li>
<li>To test the manual for errors, you can run <tt>make test</tt>
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>
<li>
In case you would like to get HTML output, you can run
<tt>make html</tt>, which will invoke [open]jade and will
create HTML output in about 30 minutes. In case of RTL
languages [Hebrew, Arabic] a special output parser [written
in PHP] runs through the output to finetune it for RTL rules.
</li>
<li>
For PHP coded output to use on a mirror site, you can run
<tt>make phpweb</tt> and expect the output in slightly more
time then <tt>make html</tt>, as this outputs more interlinks
then the HTML version. The RTL patch is applied here too. Before
the [open]jade run, a special phpweb_entities file is created
[using a PHP script] to make the php.net links relative to the
mirror sites hosting the manuals. This entity file is removed
after this build.
</li>
<li>
To get one big HTML file, you can run <tt>make bightml</tt>,
and that will produce the output in significantly in less time
then the two previous output methods, as no chunking is needed
and interlinks are easier to calculate. No RTL patch is applied
for this output so far.
</li>
<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>
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
compresses the bightml version using the iSilo format.
</li>
<li>
The PDF version [<tt>make pdf</tt>] "is created" by first using
[open]jade to convert the manual to tex format. Then jadetex is
run three times on this tex file to create a DVI [multipass is
needed to make the output look right]. Then dvipdfm is run to
create
a PDF out of the DVI. This process is not working currently, as
there are some limits in the processing tools which we managed
to step through.
</li>
<li>
To create a CHM version, the <tt>make html</tt> output is used
as a basis. A custom PHP postprocesor runs though that,
and gathers the table of contents information, and rewrites some
parts. Then hhc [the HTML Help Compiler] is run to create the CHM.
Hhc is a free program, only available for Windows.
</li>
<li>
To create an extended CHM version, you need XSLT tools [xsltproc].
You need to run <tt>make chm_xsl</tt> and then download and unbz2
the actual complete user notes package. Then you can run
<tt>make_chm</tt> in the <tt>htmlhelp</tt> dir of phpdoc [not the
CHM dir!]. This uses some PHP regex magic to rewrite some parts of
the XSL output, similarly to the normal CHM version, and also uses
hhc.
</li>
</ul>
</div>
<p>As you can see the problem with the build system is that it does
not attempt to reuse many already built parts. The html and phpweb
outputs are completely separately built for example, while they are
95% the same content (the navigation parts differ). A further problem
is that the whole manual is built everytime. That means no quick check
possibility for translators, but more importantly a huge waste of time
on the build machine, as most of the translations still have heavy
untranslated content.</p>
<p>Using PHP regex magic for providing RTL support, and building the
two CHM versions is also not an ideal solution, as those are very
vulnerable to changes in the output format. The extended CHM builds are
in fact halted because of some significant changes in the XSL output
format lately.</p>
<p>The whole point in getting rid of DSSSL is that we need some
solutions
we can customize, and modify as needed. XSLT is ideal for that as there
are some guys knowing that standard, and it is easily readable, so
anyone
can help. But itself XSLT does not solve the "build time waste"
problems.
The negative point of the XSLT based HTML generation is that when we
deal
with a translated manual, there can be encoding colissions in
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
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>
<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>
<div class="points">
Some important questions:
<ul>
<li>Where to go from DSSSL? XSLT or custom PHP solution?</li>
<li>How to get a full PDF version working again?</li>
<li>Use an xmllint based "make test" and "./configure" instead
of an [o]nsgmls based [as it is currently]?</li>
<li>Employ a distributed build system to make automatic
manual building work again?</li>
<li>Add some priorities to the build system so English manuals,
and phpweb manuals are built more often?</li>
<li>How to merge the two CHM versions, and make it
automatically
buildable?</li>
</ul>
</div>
<div class="seealso">
See also: <a
href="http://cvs.php.net/co.php/phpdoc/RFC/pdf_problems";>phpdoc/RFC/pdf_problems</a>,
<a
href="http://news.php.net/article.php?group=php.mirrors&article=18268";>Wez's
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>
</div>
</li>
<li>
<h3>Structuring the documentation</h3>
<p>Having structure 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
on with them, as we lack the expertise to customize the DSSSL sheets
for our likeing.</p>
<p>There is also no support in DocBook for that kind of see also
lists we would like to use, and there is absolutely no support for
reference part grouping. So to achive that we need to customize
DocBook somehow, or rewrite the whole manual structure. The PHP-GTK
documentation group has good experience with using a modified
DocBook DTD, which is very well supported by DocBook.</p>
<p>Still we cannot step in this direction unless the build system
is ready for the modified input. Also note that the flow of the
extensions documented in the TOC is the worst thing we can
provide for a newcomer, and we reecieved criticism for this
point many times in the past.</p>
<div class="points">
Some important questions:
<ul>
<li>Is it OK to use a modified DocBook DTD?</li>
<li>Is the manpage like function documentation still
preferred?</li>
</ul>
</div>
<div class="seealso">
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
</div>
</li>
<li>
<h3>PHP 5 and PECL</h3>
<p>It is a largely open question when and how we should document
the upcoming new features in PHP 5. As well as how to document the
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>
<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
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,
or leave some at phpdoc.</p>
<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.</p>
<div class="points">
Some important questions:
<ul>
<li>How / when to document PHP 5 features?</li>
<li>What extensions will be moved to PECL and when?</li>
</ul>
</div>
<div class="seealso">
I don't know of any material to put here...
</div>
</li>
<li>
<h3>Better 'documentation experience' for users</h3>
<p>This point includes discussion of ideas for improving the
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.</p>
<p>The extended CHM is the best version for onscreen browsing
on Windows. We should build on it's experience and add new
features to other formats too [eg. include user notes in
downloadable versions?].</p>
<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
converting it to PDF]? Would a self-hosted manual obsolote the
CHMs?</p>
<div class="seealso">
See also the parts on different formats in the <a
href="#buildsys">build
system topic</a>.
</div>
</li>
<li>
<h3>Separation of 'PHP Manual' and 'PHP Internals Manual'</h3>
<p>Having 'PHP Internals' information in a manual mainly focused
at users leads to many confusions. Development pages can be
returned in searches, users can get there inadvertantly. Having
these sections in the manual also slows down the builds, and makes
the manual downloads bigger for no reason. Those parts are not used
by most of the reader base.</p>
<p>There should be an easy way to separate the manual from the
internals part and have two books separately built. The internals
book would include information on development for PHP 3 / 4 and
the streams development docs currently included in the manual. How
this can be integrated in the current build system is still a
question.</p>
<div class="points">
Some important questions:
<ul>
<li>Do we need translation support for the Internals
Manual?</li>
<li>Should it sit in the phpdoc CVS module?</li>
<li>How to integrate it with the build system?</li>
</ul>
</div>
<div class="seealso">
I don't know of any material to put here...
</div>
</li>
</ol>
<a name="contact"></a>
<h2>Contact</h2>
<p>Contact <a href="mailto:[EMAIL PROTECTED]">the PHP Documentation
Mailing List</a> in case of questions and suggestions for discussions. In
case of suggestions regarding this page or personal problems, please
write to Goba (<span class="linklooking"
title="This is not a real link, you know why :)">goba at php dot
net</span>)</p>
</div>
</body>
<!-- 2002 agenda: http://marc.theaimsgroup.com/?l=phpdoc&m=101558612304019 -->
</html>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
