1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
|
<!-- 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 156097 2004-04-15 10:29:49Z didou $</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>The
meeting will be on July 10, and will be a whole day event.</strong>
Location: Room 1.32 (located in the conference hall).
</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>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>Kuecuekyilmaz, <strong>Hakan</strong></li>
<li>Lerdorf, <strong>Rasmus</strong></li>
<li>Merz, <strong>Alexander</strong></li>
<li>Rethans, <strong>Derick</strong></li>
<li>Schmid, <strong>Egon</strong></li>
<li>Schroder, <strong>Kai</strong></li>
<li>Stocker, <strong>Christian</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 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
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, add those to the page in phpdoc CVS, or
<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, 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, 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 (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.
And how are they defined?</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 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>
<li>Where will the required diff -u and make test commands
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>
</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 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
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>
<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 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">
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.
Also, the <a href="http://marc.theaimsgroup.com/?l=phpdoc&m=99618446902193">notes
maintainer proposal</a>.
</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 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 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 the 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.
<br/>
There is a special pdfjadetex tool that creates PDF output from
the generated tex source right away instead of DVI, but this is
even more limited by hard coded table sizes within the tex binaries.
<br/>
The 3 passes are needed to render the final document as tex
uses a streaming approach, creating output immediately from the
input and the state information collected up to that point.
So e.g. a table of contents at the beginning of a document can't
be created on the first run as the chapter and section titles
are not known yet. These are collected on the first run and put
into a special .aux file. On the second run the table of contents
is created from this .aux file. Due to the now insertet toc all
following pages are shifted right so that the page numbers in the
toc are not yet correct. So a final third run is needed after
inserting the toc (and other stuff referencing page numbers or
symbolic labels). On very rare occasions even a 4th run is needed
as e.g. a page number changing from 99 to 100 in the 3rd run may
lead to an additional page break somewhere in the document ...
</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>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" 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. Wez's livedocs will be the base of this for the PHP docs.</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>. 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 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
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>
<li>What is higher priority in the above suggestion list
(reference grouping, structured see alsos, manpage
structure)?</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, so users won't get confused.</p>
<p>With the upcoming PHP releases and with PHP 5, many extension will
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,
or leave some (like the bundled extensions) 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. Also, before anything is officially moved
out of phpdoc, it should be available online in the peardoc manual.</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>
<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>
</ul>
</div>
<div class="seealso">
<a href="http://marc.theaimsgroup.com/?l=phpdoc&m=103856748014419">Some ideas</a>,
<a href="http://cvs.php.net/co.php/phpdoc/RFC/removed_extensions">phpdoc/RFC/removed_extensions</a>,
<a href="http://cvs.php.net/co.php/phpdoc/RFC/moved_extensions">phpdoc/RFC/moved_extensions</a>, and a
<a href="http://www.faqts.com/knowledge_base/view.phtml/aid/22154/fid/1150">PHP 5 Faqt</a> that links to PHP 5 related resources.
</div>
</li>
<li>
<h3>What do do with PHP 3 documentation</h3>
<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 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">
<a href="http://marc.theaimsgroup.com/?l=phpdoc&m=104328040919058">Proposal summary</a>
</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. 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
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 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>PECL internals are also affected, so this Internals Manual
should cover both?</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:phpdoc@lists.php.net">the PHP Documentation
Mailing List</a> in case of questions and suggestions for discussions. In
case of suggestions regarding this page, please
write to Goba (<span class="linklooking"
title="This is not a real link, you know why :)">goba at php dot net</span>)
or fix the page yourself in phpdoc/RFC/2003_meeting_agenda.html.</p>
</div>
</body>
<!-- 2002 agenda: http://marc.theaimsgroup.com/?l=phpdoc&m=101558612304019 -->
</html>
|
