[Lazarus] FPDoc tracker

Michael Van Canneyt michael at freepascal.org
Sat Jul 16 10:40:18 CEST 2011



On Fri, 15 Jul 2011, Hans-Peter Diettrich wrote:

> Martin schrieb:
>
>> The 2ndary file could have a checksum of the node n the primary file. then 
>> it can check, if the primary file was modified. The checksum must be in a 
>> way, that ignores formatting, etc. (maybe even minor spelling fixes)
>
> A "raw text" output (without attributes) would be helpful, in addition to 
> HTML etc. formats.

A text output format exists.

>
>> Maybe easier, if the primary file has a version (for each node), then the 
>> 2ndary can simply store which version it currently reflects.
>> - With changes to the primary, the user can decide, if it is a new version, 
>> or a spelling fix (version kept)
>> - With changes to the 2ndary, the user decides, if the version should 
>> follow (or same as for primary, it was a spelling fix)
>
> I've already tried to add according comments to the sources, but I doubt that 
> any contributor will maintain version numbers himself. A practical solution 
> IMO should be built into the editors (FPDocEditor, LazDE), which store 
> version information in additional XML tags, and increment version numbers 
> automatically or on confirmation (minor/major change) by the contributor.
>
>
>> As for the checksum, I have a similar idea/wish, for checksumming the 
>> source code documented, so one can find documentation which must be 
>> updated, due to source changes.
>
> Sounds good :-)
>
> Again the solution will require additional XML tags, and tools that update 
> this information.

I think you should use attributes instead of tags. 
fpdoc is not very forgiving of 'unknown' tags. 
It does not care so much about attributes, though.

>
> BTW do there exist intentions to extend the XML files for e.g. multiple 
> languages? When all versions can co-exist in one file, it would be much 
> easier to track modifications, and to find consequently affected text.

The original idea was to add a 'language' attribute to the <element> tag.
Thus allowing multiple elements with the same name, but different languages. 
The '--language' command-line option would then be used to select the correct tag.
However, I never got round to implementing it.

Experience with the FPC website shows that chances of having multi-language 
documentation are virtually 0. Basically, I think the FPC/Lazarus community 
is too small for the effort it takes.

Michael.




More information about the Lazarus mailing list