On Thu, Jul 21, 2011 at 23:11, Hannes Magnusson <hannes.magnus...@gmail.com> wrote: > On Jul 21, 2011 9:12 PM, "Adam Harvey" <ahar...@php.net> wrote: >> On 21 July 2011 12:07, Hannes Magnusson <hannes.magnus...@gmail.com> wrote: >>> On Thu, Jul 21, 2011 at 20:14, Adam Harvey <ahar...@php.net> wrote: >>>> On 21 July 2011 07:15, Hannes Magnusson <hannes.magnus...@gmail.com> wrote: >>>>> A (short) list of "authors" or a "group" needs to exist due to licensing >>>>> issues. >>>>> How to generate that one I've no idea. >>>> >>>> Are you sure about that? I think you'll find that copyright is held by >>>> all contributors individually, so it's actually more accurate to point >>>> to the entire list for licensing purposes. >>> >>> That would mean we would need the approval of every single person in >>> that gigantic list to change the license. >>> It was hard enough to track down and contact the less-then-10 people >>> lasttime >> >> Yep. That's why Wikipedia had to get the GFDL changed to allow them to >> convert to CC — it was the only feasible way of doing it, since they >> couldn't contact all their contributors. >> >> It is a pain. > > Right. Therefore having a little group of some sort makes that epic > pain into "just" much annoyance. > > > >> >>>>> I would like a "NEWS"/"ChangeLog" listing, similar to what php-src does. >>>>> That would serve the dual purpose of improving crediting of people >>>>> actually working on the docs on daily basis, and letting the user know >>>>> what is new within the docs (so he can pay attention to modifications >>>>> to his favorite doc page), and bugfixes etc etc. >>>> >>>> It would be nice. We should be able to auto-generate something, >>>> really, based on commits. >>> >>> >>> I don't like the idea of autogenerating such list. The black list >>> would be painful to manage (i.e. how would remove WS commits and >>> random weirdness?) >> >> I wouldn't even try to. They're not that big a percentage of our commits. >> >>> I'm sure it will take few weeks to get used to update a "NEWS" file on >>> every bugfix/new additions, and drive-by-committers will probably not >>> to do.. but in the longterm I still think its a better option. >>> >>> We could then manually rotate the list every once in a while, or even >>> create a rule in PhD to only list the last "100 entries" or whatever. >> >> How's this going to integrate with the online doc editor? > > > I suppose in the first few weeks you'd have to manually edit the file. > Afterwards we could add, on committing, "what do you want to have as > NEWS entry?" or when creating the patch or whatever. I'm sure we can > come up with something. > > As for the presentation, I'd like it to be displaid on the frontpage > somehow, and on the rendered page itself, and on > php.net/manual/en/whats.new.in.the.docs.php or something along that > way. > > The news entry could be contain the bug#, date, message, xml:id and username. > That way we could easily show the "edits to this page within the last > month (plus comments)", aggregate "who makes most bugfixes" and "other > modifications" and whatever....
Attached is a patch that adds a changelog to the manual. The initial list of entries is extracted from svn log, any commits as of "now" should be manually added (and the initial list probably modified). The patch adds a paragraph to the manual frontpage with a link to the changelog, which is implement as an chapter under the PHP Manual book (which currently only contained preface). I dropped the idea of adding xml:id to the changelog entries (what if you edit bucketloads of files?), but we could do that later and expand more upon the idea. As for phd, it just prints this out in a table. Later on I would like to create some sort of paginated list, or simply drop entries older then X months. Furthermore, adding links from the username entry to people.php.net would be fun, and automatically scanning the message for "fixed bug #xyz" and link it to bugsweb etc etc etc. So. Every changelog entry should look as follows: <revision> <date>2011-08-31</date> <authorinitials>bjori</authorinitials> <revremark>Fixed bug#xyz</revremark> </revision> The current <revremark> entries are extracted from the commit messages, but it would be nice if we could make them "audience readable" when we start adding changelogs manually. Since this requires modifications in PhD (to support the revision, authorinitials and revremark elements) we'll need to roll out a new PhD release before being able to deploy this, I do however intend to commit the manual-changelog.xml file (without enabling it in the build) so we can start populating it. -Hannes
Index: phpdoc/en/trunk/manual-changelog.xml =================================================================== --- phpdoc/en/trunk/manual-changelog.xml (revision 0) +++ phpdoc/en/trunk/manual-changelog.xml (revision 0) @@ -0,0 +1,601 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 295472 $ --> + +<appendix xml:id="manual-changelog" xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink";> + <title>Changelog</title> + + <revhistory> + + <revision> + <date>2011-08-31</date> + <authorinitials>laruence</authorinitials> + <revremark>Add new lua docs</revremark> + </revision> + + <revision> + <date>2011-08-31</date> + <authorinitials>colder</authorinitials> + <revremark>Mention that __autoload is somehow outdated</revremark> + </revision> + + <revision> + <date>2011-08-30</date> + <authorinitials>joey</authorinitials> + <revremark>DOMNodeList is Iterable</revremark> + </revision> + + <revision> + <date>2011-08-30</date> + <authorinitials>kristina</authorinitials> + <revremark>More info on connection pooling</revremark> + </revision> + + <revision> + <date>2011-08-30</date> + <authorinitials>kristina</authorinitials> + <revremark>add "db" option</revremark> + </revision> + + <revision> + <date>2011-08-30</date> + <authorinitials>bjori</authorinitials> + <revremark>Fixed bug#49294 (ReflectionExtension::info doesn't return the info)</revremark> + </revision> + + <revision> + <date>2011-08-30</date> + <authorinitials>bjori</authorinitials> + <revremark>Add a see also for the notification function declaration</revremark> + </revision> + + <revision> + <date>2011-08-30</date> + <authorinitials>bjori</authorinitials> + <revremark>Fixed bug#30157, stream_tell() isn't called by ftell(), only when seeking</revremark> + </revision> + + <revision> + <date>2011-08-30</date> + <authorinitials>bjori</authorinitials> + <revremark>point to the session handler rather then apc</revremark> + </revision> + + <revision> + <date>2011-08-30</date> + <authorinitials>bjori</authorinitials> + <revremark>Fixed bug#55430, introduce the session.upload_progress family to the world</revremark> + </revision> + + <revision> + <date>2011-08-29</date> + <authorinitials>gwynne</authorinitials> + <revremark>Add documentation for the JSON_UNESCAPED_UNICODE flag (bug #53946)</revremark> + </revision> + + <revision> + <date>2011-08-28</date> + <authorinitials>aharvey</authorinitials> + <revremark>Fix doc bug #55519 (mt_rand only generetes even 64 bits numbers) by adding a + cautionary note to the mt_rand() documentation.</revremark> + </revision> + + <revision> + <date>2011-08-27</date> + <authorinitials>bradley</authorinitials> + <revremark>Update AMQP documentation to follow documentation standards.</revremark> + </revision> + + <revision> + <date>2011-08-27</date> + <authorinitials>lytboris</authorinitials> + <revremark>introducing SNMP::ERRNO_OID_PARSING_ERROR constant</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>bradley</authorinitials> + <revremark>Add examples to AMQPQueue::get and AMQPQueue::ack documentation.</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>sebastian</authorinitials> + <revremark>Fix wording.</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>sebastian</authorinitials> + <revremark>Fix documentation of ReflectionClass::newInstanceWithoutConstructor().</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>bradley</authorinitials> + <revremark>Fix incorrect constant name and add missing parameter name.</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>shein</authorinitials> + <revremark>Fixed parameter description.</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>salathe</authorinitials> + <revremark>name variables better in simplexml basic examples (hat tip Gordon Oheim)</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>shein</authorinitials> + <revremark>Moved description of "empty" values beyond the literal tag to allow its translation.</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>salathe</authorinitials> + <revremark>fix build</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>salathe</authorinitials> + <revremark>see also mb_split (thanks Olivier Pons)</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>sebastian</authorinitials> + <revremark>Document ReflectionClass::newInstanceWithoutConstructor().</revremark> + </revision> + + <revision> + <date>2011-08-26</date> + <authorinitials>bjori</authorinitials> + <revremark>Fix syntax highlighting</revremark> + </revision> + + <revision> + <date>2011-08-25</date> + <authorinitials>nikic</authorinitials> + <revremark>Fix Doc Bug #55454: Apparent errors in the examples</revremark> + </revision> + + <revision> + <date>2011-08-25</date> + <authorinitials>takagi</authorinitials> + <revremark>fix build.</revremark> + </revision> + + <revision> + <date>2011-08-25</date> + <authorinitials>nikic</authorinitials> + <revremark>Fix Doc Bug #54663: chdir() emits E_WARNING</revremark> + </revision> + + <revision> + <date>2011-08-25</date> + <authorinitials>nikic</authorinitials> + <revremark>Fix Bug #55243: Namespaces also affect interfaces</revremark> + </revision> + + <revision> + <date>2011-08-25</date> + <authorinitials>nikic</authorinitials> + <revremark>Fix Doc Bug #55452: Confusing description for mb_strcut()</revremark> + </revision> + + <revision> + <date>2011-08-25</date> + <authorinitials>salathe</authorinitials> + <revremark>wrap and dot</revremark> + </revision> + + <revision> + <date>2011-08-25</date> + <authorinitials>iliaa</authorinitials> + <revremark>Updated curl-setopt docs re-SSL options</revremark> + </revision> + + <revision> + <date>2011-08-25</date> + <authorinitials>cubrid</authorinitials> + <revremark>add primary key, blob, unsigned and zerofill in cubrid_fetch_field function</revremark> + </revision> + + <revision> + <date>2011-08-25</date> + <authorinitials>shein</authorinitials> + <revremark>Fixed wrong parameter description.</revremark> + </revision> + + <revision> + <date>2011-08-25</date> + <authorinitials>chx</authorinitials> + <revremark>Added PATH_SEPARATOR to open_basedir and a brief explanation of it into reference/dir/constants.xml</revremark> + </revision> + + <revision> + <date>2011-08-24</date> + <authorinitials>kristina</authorinitials> + <revremark>Changed second option to storeUpload</revremark> + </revision> + + <revision> + <date>2011-08-24</date> + <authorinitials>nikic</authorinitials> + <revremark>Some more changes for 5.4s E_ALL with E_STRICT in docs</revremark> + </revision> + + <revision> + <date>2011-08-23</date> + <authorinitials>bjori</authorinitials> + <revremark>There is no such thing anymore (and hasn't for years)</revremark> + </revision> + + <revision> + <date>2011-08-23</date> + <authorinitials>bjori</authorinitials> + <revremark>link these, like all other ini options</revremark> + </revision> + + <revision> + <date>2011-08-22</date> + <authorinitials>salathe</authorinitials> + <revremark>getinneriterator() can return traversable (doc #55480)</revremark> + </revision> + + <revision> + <date>2011-08-22</date> + <authorinitials>salathe</authorinitials> + <revremark>iteratoriterator method return types (doc #55480)</revremark> + </revision> + + <revision> + <date>2011-08-21</date> + <authorinitials>lytboris</authorinitials> + <revremark>fixing documentation per bug #53342</revremark> + </revision> + + <revision> + <date>2011-08-20</date> + <authorinitials>takagi</authorinitials> + <revremark>fix build.</revremark> + </revision> + + <revision> + <date>2011-08-20</date> + <authorinitials>kalle</authorinitials> + <revremark>Make migration54 accessable -- Added a warning to the top of the page letting viewers know that this is still a WIP</revremark> + </revision> + + <revision> + <date>2011-08-20</date> + <authorinitials>lytboris</authorinitials> + <revremark>document FR #55312, #42918</revremark> + </revision> + + <revision> + <date>2011-08-19</date> + <authorinitials>salathe</authorinitials> + <revremark>examples ws</revremark> + </revision> + + <revision> + <date>2011-08-19</date> + <authorinitials>rquadling</authorinitials> + <revremark>Ignore entities.*.xml</revremark> + </revision> + + <revision> + <date>2011-08-19</date> + <authorinitials>salathe</authorinitials> + <revremark>fix xi:include to point to mongopool methods</revremark> + </revision> + + <revision> + <date>2011-08-19</date> + <authorinitials>rquadling</authorinitials> + <revremark>PHP4/PHP5 => PHP 4 / PHP 5</revremark> + </revision> + + <revision> + <date>2011-08-19</date> + <authorinitials>shein</authorinitials> + <revremark>Standartized description of iconv-str(r)pos functions.</revremark> + </revision> + + <revision> + <date>2011-08-19</date> + <authorinitials>shein</authorinitials> + <revremark>WS</revremark> + </revision> + + <revision> + <date>2011-08-18</date> + <authorinitials>kristina</authorinitials> + <revremark>added MongoPool functions</revremark> + </revision> + + <revision> + <date>2011-08-18</date> + <authorinitials>johannes</authorinitials> + <revremark>nitpicking: PHP 5, not PHP5</revremark> + </revision> + + <revision> + <date>2011-08-18</date> + <authorinitials>rquadling</authorinitials> + <revremark>getrandmax returns 2^15 - 1, not 2 ^ 15 on Windows (and maybe others). + Fix bug #55446</revremark> + </revision> + + <revision> + <date>2011-08-18</date> + <authorinitials>rquadling</authorinitials> + <revremark>Ignore entities.*.xml</revremark> + </revision> + + <revision> + <date>2011-08-18</date> + <authorinitials>salathe</authorinitials> + <revremark>singleton is bad example for traits</revremark> + </revision> + + <revision> + <date>2011-08-18</date> + <authorinitials>salathe</authorinitials> + <revremark>fix traits visibility example</revremark> + </revision> + + <revision> + <date>2011-08-17</date> + <authorinitials>bjori</authorinitials> + <revremark>add umask() to seealso as suggested in bug#55302</revremark> + </revision> + + <revision> + <date>2011-08-17</date> + <authorinitials>bjori</authorinitials> + <revremark>Document mysql[i].allow_local_infile, see bug#55404</revremark> + </revision> + + <revision> + <date>2011-08-17</date> + <authorinitials>bjori</authorinitials> + <revremark>Fixed bug#55386 missing return value</revremark> + </revision> + + <revision> + <date>2011-08-17</date> + <authorinitials>bjori</authorinitials> + <revremark>Sort the changelog properly, kill bogus warning and wrong error return value. fixes bug#55426</revremark> + </revision> + + <revision> + <date>2011-08-17</date> + <authorinitials>bjori</authorinitials> + <revremark>Fixed bug#55429 (Description of this function is incorrect and awkwardly written)</revremark> + </revision> + + <revision> + <date>2011-08-17</date> + <authorinitials>bjori</authorinitials> + <revremark>blah. fix build</revremark> + </revision> + + <revision> + <date>2011-08-17</date> + <authorinitials>bjori</authorinitials> + <revremark>Add a link explaining what UCA is, see bug#55435</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>kristina</authorinitials> + <revremark>added MongoLog class</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>kristina</authorinitials> + <revremark>added more examples for cursor exceptions</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>cweiske</authorinitials> + <revremark>- Fix default mode for php and phps files + - Talk about adding an empty array instead of defining one yourself</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>rquadling</authorinitials> + <revremark>Linking magic methods.</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>rquadling</authorinitials> + <revremark>Image is a jpg, not a renamed png.</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>rquadling</authorinitials> + <revremark>Standardise on single style of quotes for XML tag.</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>rquadling</authorinitials> + <revremark>Amended example to show the value returned by the imap_utf7_encode() call.</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>rquadling</authorinitials> + <revremark>Ignore entities.*.xml</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>rquadling</authorinitials> + <revremark>Link serialize() and unserialize() to __sleep() and __wakeup().</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>rquadling</authorinitials> + <revremark>Added complete svn:keyword list</revremark> + </revision> + + <revision> + <date>2011-08-16</date> + <authorinitials>shein</authorinitials> + <revremark>Fixed WS.</revremark> + </revision> + + <revision> + <date>2011-08-15</date> + <authorinitials>rquadling</authorinitials> + <revremark>Created migration guide to 5.4. Lots of placeholders and examples, but could be restructured if more appropriate headings needed.</revremark> + </revision> + + <revision> + <date>2011-08-15</date> + <authorinitials>rquadling</authorinitials> + <revremark>E_ALL will contain E_STRICT in PHP 5.4.x</revremark> + </revision> + + <revision> + <date>2011-08-15</date> + <authorinitials>nikic</authorinitials> + <revremark>Add substr_compare in See Also sections of strn?(case)?cmp</revremark> + </revision> + + <revision> + <date>2011-08-14</date> + <authorinitials>colder</authorinitials> + <revremark>Some mysql functions work differently with respect to the link id, mysql_close does not try to open one if none is found. There are probably other such cases</revremark> + </revision> + + <revision> + <date>2011-08-14</date> + <authorinitials>nikic</authorinitials> + <revremark>Fix doc bug #55381 "Incorrect spelling"</revremark> + </revision> + + <revision> + <date>2011-08-14</date> + <authorinitials>vrana</authorinitials> + <revremark>Link http_response_code and headers_list</revremark> + </revision> + + <revision> + <date>2011-08-14</date> + <authorinitials>vrana</authorinitials> + <revremark>No note in changelog</revremark> + </revision> + + <revision> + <date>2011-08-12</date> + <authorinitials>vrana</authorinitials> + <revremark>Remove unused file</revremark> + </revision> + + <revision> + <date>2011-08-12</date> + <authorinitials>vrana</authorinitials> + <revremark>Link</revremark> + </revision> + + <revision> + <date>2011-08-12</date> + <authorinitials>vrana</authorinitials> + <revremark>Suhosin extension</revremark> + </revision> + + <revision> + <date>2011-08-12</date> + <authorinitials>vrana</authorinitials> + <revremark>Whitespace</revremark> + </revision> + + <revision> + <date>2011-08-12</date> + <authorinitials>vrana</authorinitials> + <revremark>History in changelog</revremark> + </revision> + + <revision> + <date>2011-08-11</date> + <authorinitials>salathe</authorinitials> + <revremark>fix example (mysqli::connect_* are properties not methods, doc #55405)</revremark> + </revision> + + <revision> + <date>2011-08-11</date> + <authorinitials>shein</authorinitials> + <revremark>Fixed description of returned value on error.</revremark> + </revision> + + <revision> + <date>2011-08-10</date> + <authorinitials>cweiske</authorinitials> + <revremark>fix example description</revremark> + </revision> + + <revision> + <date>2011-08-09</date> + <authorinitials>laruence</authorinitials> + <revremark>Deleted no use files</revremark> + </revision> + + <revision> + <date>2011-08-09</date> + <authorinitials>rquadling</authorinitials> + <revremark>Remove entities.functions.xml</revremark> + </revision> + + <revision> + <date>2011-08-09</date> + <authorinitials>salathe</authorinitials> + <revremark>correct changelog order</revremark> + </revision> + + <revision> + <date>2011-08-08</date> + <authorinitials>rquadling</authorinitials> + <revremark>Ignore entities.*.xml sgml-default-dtd-file:"~/.phpdoc/manual.ced"</revremark> + </revision> + + </revhistory> + +</appendix> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> + + Index: phpdoc/en/trunk/bookinfo.xml =================================================================== --- phpdoc/en/trunk/bookinfo.xml (revision 315861) +++ phpdoc/en/trunk/bookinfo.xml (working copy) @@ -11,6 +11,13 @@ <holder>the PHP Documentation Group</holder> </copyright> + <printhistory> + <para> + For a list of recent updates to the manual, see the + <link linkend="manual-changelog">changelog</link>. + </para> + </printhistory> + <legalnotice xml:id="copyright" xmlns:xlink="http://www.w3.org/1999/xlink";> <title>Copyright</title> <simpara> Index: phpdoc/doc-base/trunk/manual.xml.in =================================================================== --- phpdoc/doc-base/trunk/manual.xml.in (revision 315874) +++ phpdoc/doc-base/trunk/manual.xml.in (working copy) @@ -44,6 +44,7 @@ <book xml:id="manual"> <title>&PHPManual;</title> &preface; + &manual-changelog; </book> <book xml:id="getting-started"> Index: phd/trunk/phpdotnet/phd/Package/Generic/XHTML.php =================================================================== --- phd/trunk/phpdotnet/phd/Package/Generic/XHTML.php (revision 315861) +++ phd/trunk/phpdotnet/phd/Package/Generic/XHTML.php (working copy) @@ -16,6 +16,7 @@ 'authorgroup' => 'format_authorgroup_author', ), 'authorgroup' => 'div', + 'authorinitials' => 'format_entry', 'appendix' => 'format_container_chunk_top', 'application' => 'span', 'blockquote' => 'blockquote', @@ -32,7 +33,10 @@ 'co' => 'format_co', 'colophon' => 'format_chunk', 'copyright' => 'format_copyright', - 'date' => 'p', + 'date' => array( + /* DEFAULT */ 'p', + 'revision' => 'format_entry', + ), 'editor' => 'format_editor', 'edition' => 'format_suppressed_tags', 'email' => 'format_suppressed_tags', @@ -182,6 +186,7 @@ 'personblurb' => 'format_div', 'phrase' => 'span', 'preface' => 'format_chunk', + 'printhistory' => 'format_div', 'primaryie' => 'format_suppressed_tags', 'procedure' => 'format_procedure', 'productname' => 'span', @@ -206,6 +211,9 @@ 'refnamediv' => 'div', 'releaseinfo' => 'div', 'replaceable' => 'span', + 'revhistory' => 'format_table', + 'revision' => 'format_row', + 'revremark' => 'format_entry', 'row' => 'format_row', 'screen' => 'format_screen', 'screenshot' => 'format_div', @@ -1379,6 +1387,8 @@ public function format_table($open, $name, $attrs, $props) { if ($open) { $this->cchunk["table"] = true; + // Initialize an empty tgroup in case we never process such element + Format::tgroup(array()); $idstr = ''; if (isset($attrs[Reader::XMLNS_XML]["id"])) { $idstr = ' id="' . $attrs[Reader::XMLNS_XML]["id"] . '"'; @@ -1485,7 +1495,7 @@ return '<td class="empty"> </td>'; } if ($open) { - $dbattrs = Format::getColspec($attrs[Reader::XMLNS_DOCBOOK]); + $dbattrs = (array)Format::getColspec($attrs[Reader::XMLNS_DOCBOOK]); $retval = ""; if (isset($dbattrs["colname"])) {
