> Wez came up with the idea of putting author information into the > refentries and sections, which should make it quite easy to give credit. > This can be done with a <docinfo> in a <refentry>, and a <sectioninfo> > for a <section>. Both of these take on an <authorgroup> element which > may contain all necessary information. This method lets people decide on > who to give credit to on a small scale, and enables automation of > extracting credit information from XML files. > > Start from http://www.docbook.org/tdg/en/html/authorgroup.html to get > more information on the tag and possible parents. > > For translated versions, the nicknames can be fetched from the Revision > comments, where those are appropriately specified. For the original > English text, everything not added by Hartmut [who have done file > splits, movearounds] can probably be credited to the first committer. > > For the other files, people should just complain that they added it, and > it can be done by hand (they provide a link to their commit). For the > language, tutorial, and other sections it can be done by hand for now.
I don't know if this is a good idea... Having a tag in every file? And what names would be listed? The original writer of the file? The guy who added some examples? The guy who fixed some bugs on that file? Isn't easy! I would vote to have all names together somewhere in the documentation (frontpage, appendix,....). > There are other type of contributors, who we cannot assign to individual > XML files. So there should be a separate [maybe partially generated] > credits file with their details. > > Types of other contributors: > - user note maintainers: > andrew, meebay, didou, ... The list can be generated from > the php-notes mailing list archive. Wez is going to do make > a script pull it out from archives, and after that we're going > to put up guidelines for who is a maintainer and who is not. > - techinical editors: > hartmut, egon, goba ... Techical editors [unless someone > finds a better name] are those who edit the documentation > and contribute to the build system helping the work of > authors and translators. > - authors: > stig, philip ... Authors are for one part those who are > historically preserved, and are not available to connect > to XML files as authors. For another part, they are those > who contribute content on a large scale. > > It is generally quite hard to put people in a group, thus it will be > decided by group consensus. A person is not limited to be listed in only > one group. Agree here > The author information detailed above is used to print out the author's > name on individual documentation pages in the footer with a small font. > If there is no author info section for a specific page in the XML file, > then the author[s] of the parent is shown. > > The author info will also be used to generate a full listing of every > contributor involved in the documentation process. This list will be > presented on the bookinfo page. For translations, the translators names > will show below the authors in a separate section. > > History should be preserved/maintained in all the crediting systems > involved. The idea here was to use livedocs to display the author along with the file revision AFAIK. As I stated before, I think isn't really need to have so much credit. > The idea of presenting the author of the PHP extension itself also came > up, and was generally agreed on. The documentation system can grab the > list of authors from the php-src/EXTENSIONS file, and will generate > extension specific author information by the side of the documentation > authors' list. Yes, we may add the authors... And what about update the names in phpinfo()? :-) Nuno
