Eike Lange wrote:
Hi!
I would like to help writing documentation for gpc.
My project, writing german documentation for gpc died because nobody was interested helping me and its too much for just one man.
I would prefer to discuss documentation-related topics on the gpc-doc-mailinglist (gpc-doc@gnu.de) .
There are still some questions left:
- Is Texinfo 4.0 ok?
I think so. The current documentation works with 4.0 (might also work with older versions, but I didn't test it). I plan to use a new Texinfo version when it supports HTML better (i.e., supports splitting it into multiple files -- until then I use texi2html to generate the HTML).
- Which options do you use to create the diffs
Those in the script/mkdiff script. Those who are going to work on the documentation regularly might want to ask Peter for write access to the doc directory in the CVS.
- Are there any documentation-standards, I have to recognize?
I use the following rules (probably forgot some). GPC comes with a script check-doc that checks some of them.
- General:
- Should work with makeinfo, texi2html and texi2dvi, of course. -- Usually, it's enough to run makeinfo regularly and check the others only once in a while. TeX (run by texi2dvi) will sometimes warn about overfull hboxes -- but this is mostly a problem when mentioning long URLs. If there are errors, makeinfo seems to give the best error messages.
- Use available Texinfo formatting as well as possible ;-), e.g. @samp for identifiers etc., @example for longer code examples (don't indent the complete examples -- i.e., of course, indent blocks within the code as usual, but start the main block at the first column).
- Use logical formatting rather than physical formatting when possible (e.g. @samp etc., lists, tables rather than @tt, @sp or "space formatting").
- Write many index entries (with @cindex)...
- Indicate omissions or questionable parts in the documentation with something like `@c @@@@ blah blah...', so future documentation writers will see the problems. (Or ask about them in the list...)
- The GNU Coding Standards (chapter `Documentation' in standards.texi) also contain some hints.
- Reference:
- Sorted alphabetically (of course)
- Complete entries (by comparing it with the compiler source where the keywords and built-in identifiers are "declared") -- sure, currently many entries are just skeletons, the scripts just checks that they're there...
- Complete subscetions (Synopsis, Description, Conforming to, Example, See also) and cindex entry
- Example programs:
- Between `@example' ... `@end example'
- They are extracted to files under docdemos in binary distributions automatically by the extract-doc-demos script.
- Should compile without problems. (check-doc calls extract-doc-demos to extract them to a temporary directory and then tries to compile each of them, that's why running check-doc takes a while.)
- Do not have to do any useful task when run (that's what the programs in the demos directory are for), just demonstrate how to do something for someone who reads them...
- The first line after @example must contain `program', `module' or `unit' in the first column. The file (under docdemos) name will be the program/unit/module's name (converted to lower case, and with `.pas' appended). For non-Pascal files, the first line after @example must contain "File `filename.foo':". -- Currently, there's a lot of code fragments without such a heading line. For now, these fragments are ignored by extract-doc-demos. Whenever possible, they should be extended to a complete program.
- A demo program for a identifier `Foo' (in the reference) should be called `FooDemo', and other demos (in other chapters) should usually also have names ending in `Demo'.
- To cater for Dos systems, the names should be unique in the first 8 characters (they may be longer and will be truncated by Dos utilities). So, e.g., when you have several demos for `FooBar', call them `FooBar1Demo', `FooBar2Demo', etc., not `FooBarDemo1' etc. ...
About the structure of the documentation:
I think currently (apart from internals which is meant for GPC developers rather than users and not so important for now), all chapters except programming and reference are up to date and don't need much work. This is not as good as it sound since these are the two largest chapters...
The structure of reference is clear (alphabetical list of all keyowrds and built-in identifeiers, see above).
The structure of programming certainly needs improvement (several sections have been collected there from various places). Dominik (who should be on this list) told me he has some ideas and you probably have some, too, so perhaps we can discuss them here...
Let me start: I think the last two sections (RTS and units) should be moved to a separate chapter (they're more like the reference, anyway).
(The bpqstart chapter is IMHO quite ok currently, but if someone wants to add more about differences and common things between BP and GPC, this is welcome, too.)
Frank