1. Are they created by a tool or hand edited? what are the tools used?
Source documentation is generated using FPDoc. The tool makeskel parses the source file and generates a xml file which the documentation will reside in.
Documentation for e.g. IDE usage is done in the Wiki.
2. Is there some page where the original docs are created?
Sorry, I don't understand what you mean here.
3. Are they text files that are stored under version control?
As already written on the FPC list, the files are XML files available in Subversion.
4. Is there some page where previous versions are available?
Released versions are available through downloads and a finer grained control is available through Subversion.
5. How is it structured, what are the formatting rules? Is based on standards like DocBook etc?
It's a custom XML format.
6. How much of the documentation is generated from the source code? Is information about input and output parameters, and a few lines about its usage and gotchas generated from source, or does all procedures need to be documented by hand using FPDoc? Graeme mentions IPF that in his view does a better job? Do other preferably Pascal based projects use other tools with which they have had more success?
The skeleton is created using a tool, the rest is up to the persons documenting the code.
IPF is only one of the possible formats that the XML documentation can be generated to. Other examples are TXT, RTF, PDF, HTML and CHM (the latter being supported by the text mode IDE and in Lazarus through lHelp (which is distributed with Lazarus as source)). The text mode IDE can also use IPF files.
7. Are there other tools that can do a better job, such as Jira, Github etc?
GitHub has nothing to do with generating documentation. I don't know about Jira. Also FPDoc is working quite well, also it's under ower complete control, so we don't need to wait for some third party developer to extend the syntax his tool understands if we extend FPC by another language feature (hint directives and generics are nice examples).
8. I assume that docs are generated by some build tool once created. Does the submitter compile the docs on their own system and test that they are fine before getting them committed into the repository? Are the tools used identical (I see messages in the mailing list about contributors being using different versions of the tools)?
They are built locally. There should be no major differences if they are built on different systems if the tools are setup correctly.
Regards, Sven -- _______________________________________________ Lazarus mailing list [email protected] http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
