Re: [fpc-pascal] Makeskel how to add Firebird connection documentation?
On Thu, 17 Nov 2011, Reinier Olislagers wrote: Hi list, I want to document packages/fcl-db/src/sqldb/interbase/ibconnection.pp So I run this to get started: makeskel --disable-private --emit-class-separator --update --package=fcl-sqldb --input=/home/reinier/fpc271/packages/fcl-db/src/sqldb/interbase/ibconnection.pp --output=ibconnection.pp What do I enter as package? fcl-sqldb? How do I find out? (And if so, can that be documented for amateurs like me?) There is no rule. In this particular case, I would use fcl as a package. fcl-db may also be an option later on. Apart from that, is this the right command to start? You can drop the '--update', if it is the first time. and the output option should be --output=ibconnection.xml, not --output=ibconnection.pp I suppose that the output should actually be added to sqldb.xml, is that correct? Do I submit a patch or just the additional file? It should not be added to sqldb.xml, but in its own file. Each unit should come with its associated XML file. (this is not an fpdoc restriction, but something I do, it eases managing the documentation) Please note that I do not include documentation for a unit in the official docs unless all identifiers in the unit have been documented. Michael. ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Makeskel how to add Firebird connection documentation?
On 17 November 2011 11:06, michael.vancanneyt@... wrote: Apart from that, is this the right command to start? You can drop the '--update', if it is the first time. and the output option should be --output=ibconnection.xml, not --output=ibconnection.pp I would even go as far as to say Leave Makeskel completely - it generates too much noise. Just write the documentation by hand using your favourite editor. I use Lazarus IDE or MSEide. For each editor I have created a bunch of Code Template shortcuts for use with fpdoc XML files. You end up with much cleaner XML in the end - and something that is easier to maintain. I also wouldn't bother with indentation in the XML - it's of no use to fpdoc - it rather just causes problems with some of the fpdoc output targets. -- Regards, - Graeme - ___ fpGUI - a cross-platform Free Pascal GUI toolkit http://fpgui.sourceforge.net ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Makeskel how to add Firebird connection documentation?
On Thu, 17 Nov 2011, Graeme Geldenhuys wrote: On 17 November 2011 11:06, michael.vancanneyt@... wrote: Apart from that, is this the right command to start? You can drop the '--update', if it is the first time. and the output option should be --output=ibconnection.xml, not --output=ibconnection.pp I would even go as far as to say Leave Makeskel completely - it generates too much noise. Just write the documentation by hand using your favourite editor. I use Lazarus IDE or MSEide. For each editor I have created a bunch of Code Template shortcuts for use with fpdoc XML files. You end up with much cleaner XML in the end - and something that is easier to maintain. I also wouldn't bother with indentation in the XML - it's of no use to fpdoc - it rather just causes problems with some of the fpdoc output targets. I'm not sure why you recommend leaving makeskel ? I use it always for the initial file ? Given the proper parameters, it creates a very usable initial file ? Michael.___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Makeskel how to add Firebird connection documentation?
On 17 November 2011 11:45, michael.vancanneyt@ wrote: I'm not sure why you recommend leaving makeskel ? I use it always for the initial file ? Given the proper parameters, it creates a very usable initial file ? Maybe fpdoc has improved in those areas since I found the issues with makeskel generated xml files. So this might be a moot point now. From memory (this was a long time back), makeskel generates many empty tags for each element. Often documentation wasn't added in each of those empty nodes, yet the nodes exist in the xml. Lets take the following example: element name=SomeName short/ descrSome cool description/descr seealso/ example/ /element Problem #1: Some tags might get populated with content, and others might be left empty. fpdoc generate headers for some of those empty tags, even though they did not contain content. Just an example (not saying this is how fpdoc works now) Synopsis: some text here Declaration: procedure MyProc(); Parameters: [blank] Visibility: default Description: some long description here See also: [blank] Example: [blank] Like I said, fpdoc might have been fixed now. But I do remember seeing in some of the fpdoc output writers that titles were generated like Example or See Also, but then there was no content. Problem #2: Makeskel generates XML that are indented for human readability. This causes problems with some output writers. XML, HTML LaTeX might ignore whitespace or CR/LF characters in the final output, but other output writers like RTF, IPF and TXT don't. Thus your might have malformed help text. eg: element name=SomeName short/ descrThis is some long description. My second sentence. /descr example.../example /element vs element name=SomeName short/ descrThis is some long description. My second sentence./descr example.../example /element Some output writers will interpret the first example as some actual text, then CR/LF, then more text, then spaces (the indentation level of the xml nodes). So instead of ending with something like: - Description: This is some long description. My second sentence. Example: . - ...you end up with something like - Description: This is some long description. -- unwanted line break My second sentence. Example: . - ... or sometimes something like - Description: -- unwanted blank line This is some long description. -- unwanted line break My second sentence. Example: . - depending where the CR or LF characters were placed in the XML. I have seen problem #2 quite often. Next time I see it again, I'll file a bug report with a screenshot. I tried fixing this problem before by simply using something like Trim(...) inside those specific output writers, but that caused all kinds of problems. -- Regards, - Graeme - ___ fpGUI - a cross-platform Free Pascal GUI toolkit http://fpgui.sourceforge.net ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Makeskel how to add Firebird connection documentation?
On 17-11-2011 10:06, michael.vancann...@wisa.be wrote: On Thu, 17 Nov 2011, Reinier Olislagers wrote: I want to document packages/fcl-db/src/sqldb/interbase/ibconnection.pp snip stuff about makeskel What do I enter as package? fcl-sqldb? How do I find out? (And if so, can that be documented for amateurs like me?) There is no rule. In this particular case, I would use fcl as a package. fcl-db may also be an option later on. Ok, thanks. (sqldb has fcl-sqldb, that's why I guessed that name) You can drop the '--update', if it is the first time. Did that on purpose, so I won't overwrite my documentation when I copy/paste the command when updating the identifiers ;) and the output option should be --output=ibconnection.xml, not --output=ibconnection.pp Yep, typo, sorry. It should not be added to sqldb.xml, but in its own file. Each unit should come with its associated XML file. (this is not an fpdoc restriction, but something I do, it eases managing the documentation) Sensible. sqldb.xml is already fairly big. Please note that I do not include documentation for a unit in the official docs unless all identifiers in the unit have been documented. Thanks, I know, but does that include the internal (private) ones? That would seem a bit restrictive... sqldb.xml seems to have a fair number of private identifiers without any identifiers, so I guess I answered my own question... Thanks, Reinier ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Makeskel how to add Firebird connection documentation?
On 17 November 2011 12:23, Reinier Olislagers reinierolislagers@g. wrote: Thanks, I know, but does that include the internal (private) ones? That would seem a bit restrictive... No, as far as I know that restriction only applies to Public and Published visibility. -- Regards, - Graeme - ___ fpGUI - a cross-platform Free Pascal GUI toolkit http://fpgui.sourceforge.net ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Makeskel how to add Firebird connection documentation?
On Thu, 17 Nov 2011, Graeme Geldenhuys wrote: On 17 November 2011 11:45, michael.vancanneyt@ wrote: I'm not sure why you recommend leaving makeskel ? I use it always for the initial file ? Given the proper parameters, it creates a very usable initial file ? Maybe fpdoc has improved in those areas since I found the issues with makeskel generated xml files. So this might be a moot point now. From memory (this was a long time back), makeskel generates many empty tags for each element. It only generates empty tags. If you say 'update' then it generates a new file with empty tags for elements for which no tag was found. So as far as I could see, none of the issues you quoted are with makeskel ? Michael. ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Makeskel how to add Firebird connection documentation?
On 17 November 2011 14:46, michael.vancanneyt@... wrote: It only generates empty tags. If you say 'update' then it generates a new file with empty tags for elements for which no tag was found. I'm not referring to the update action of makeskel, I meant the first time you run makeskel, it generates empty tags - as it was designed. But some of fpdoc's output writers did not look if those tags are empty, they simply saw the tag, and just assumed there was content, so it always went ahead and generate some output title (eg: Description, Synopsis etc). I think even some of my last fpdoc patches fixed a few of these cases. So yes, issue #1 is probably solved by now. The second issue I mentioned happens far more often that the first issue. But yes, I guess my issues are more related to fpdoc than makeskel. So my recommendation to not use makeskel is probably more of a work-around for issue #2. -- Regards, - Graeme - ___ fpGUI - a cross-platform Free Pascal GUI toolkit http://fpgui.sourceforge.net ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
[fpc-pascal] Makeskel how to add Firebird connection documentation?
Hi list, I want to document packages/fcl-db/src/sqldb/interbase/ibconnection.pp So I run this to get started: makeskel --disable-private --emit-class-separator --update --package=fcl-sqldb --input=/home/reinier/fpc271/packages/fcl-db/src/sqldb/interbase/ibconnection.pp --output=ibconnection.pp What do I enter as package? fcl-sqldb? How do I find out? (And if so, can that be documented for amateurs like me?) Apart from that, is this the right command to start? I suppose that the output should actually be added to sqldb.xml, is that correct? Do I submit a patch or just the additional file? Once again, thanks for the help, Reinier ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
