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)

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)

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.

I'm about to write kind of a content management system for the Lazarus and FPC docs (FPDoc xml format). This system shall allow to track changes to the source documentation, so that updates can be applied e.g. to the FPDocs in other languages. I need such a CMS for updating my personal documentation, that is widely different from the "official" documentation. Another use may be the import of the Delphi documentation, that in D7 was near perfect. [as far as legal]

The idea behind this CMS is:

The CMS is based on LazDE (see lazarus/doceditor), with some adds to allow for remote control of the editor form(s).

Multiple versions of the docs are kept in separate directories, referred to as *primary* (SVN, English) and *secondary* versions. On start of the new project two instances of the LazDE editor form are shown, which allow to show corresponding files (by unit name) from two directories.

Another CMS form contains two file lists, which can be populated by selecting XML document directories (e.g. lazarus/docs/xml/), which then are scanned for all files, including subdirectories. A dblclick on an file opens both versions, from the two file lists, in the LazDE editor forms.

No technical problems, so far :-)

For the remaining functionality I need some inspiration, how changes to the docs can be tracked. One useful tool can be Git, which allows to switch quickly between revisions of the XML files, and (possibly) can allow to find commits with updates of the docs.

Since translated or otherwise modified docs do not correspond closely to the primary docs, I intend to track the "last compared" version of the primary docs along with every secondary doc file, so that a "What's New" feature can show all modifications to the primary files. For that purpose I need ideas, how changes can be solution were another directory, holding all "old" versions of the primary files, so that these files can be compared to the current versions. The comparison can be improved by checksums or similar means, so that a direct file-by-file comparison can be avoided. Perhaps also a "diff" tool can be used to find and report all differences between the files in these directories?

Furthermore the found differences must be mapped into file, item, entry (etc.) references, which allow to navigate in the editor forms to every modified item. Here it should be possible to remember the exact doc entries, whose changes have been reflected (updated...) in the secondary files. Perhaps a ToDo list should be produced, from which all handled changes can be deleted? The list can contain all undocumented items as well...

Does there exist common interest in such a documentation tool?

Who can help to implement it, be by suggestion or concrete code?

DoDi

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.

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.

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.

I'm glad to see that it's not only me, who cares about improvements to the documentation :-)

DoDi

A text output format exists.

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.

After some research I think that diff is the simplest starting point. It allows to compare directories, so that all changes can be kept in one[1] output file (ToDo list).

Then the tracker can use that file to navigate in the XML files, to find the affected elements, and finally the processed differences can be removed from the list (for later editing). After all diff sections[2] of one file are removed, the new file is copied to the reference/backup directory, for subsequent compares.

The actual work typically has to be done on different XML files, in the secondary directory. This part deserves further work...

But there's another use case, when code has been moved across units, like the recent move of the TCustomNotebook class(es) from ExtCtrls into ComCtrls. While this could be automated as well, I think that its easier to cut&paste the affected parts immediately in the XML files. Later on the code positions and hashcodes can be stored in the XML files, by makeskel, with appropriate handling of inserted/deleted/moved elements.

More automatisms can be added to makeskel, like inserting links to inherited documentation - is this required? IMO it would be a good idea to store a reference to the ancestor class with *all* classes, regardless of whether a derived class has its own documentation.

[1] How to find the directories containing separate package documentation, outside of $lazarus/docs/xml? Where is the list of all known packages stored?

[2] What's the exact meaning of the line numbers in the diff sections? Do they strictly correspond to the original line numbers, or line numbers after preceding changes (sections) have been applied?

DoDi

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.

+1
Most people seriously underestimate the huge amount of effort it takes to document something and keep that documentation up to date. Adding multiple translations to the process is a absolute mammoth task. Just take a look at the FPC/Lazarus Wiki. There are many translations, but not nearly as complete as the original English versions.

I'd say...accept the fact that FPC and Lazarus are English projects (by far the most popular language in many open-source projects) and rather spend your little free time in improving the English documentation.

The "plain text" output is rather bismal though. I am currently working on improving the RTF output [which look terrible too] and will tackle the "plain text" output after that.

Well, the community might grow when there exists better and nationalized documentation.

The idea of "build it, and they will come" only works in the movies. :-)

IMO the procedures and tools for improving the FPDoc documentation are not well known, and translations make no sense without the multi-language display feature :-(

Improvements to fpdoc is good, but don't expect multi-language documentation over night though. But they maybe I am underestimating the force of the non-English community. :-)

As for fpdoc editors and how to keep the XML files in sync with the source code - especially after refactoring. It's really simple... Just do it manually. :-) Firstly do a targeted search & replace fixing the tags to there new names, then cut the documentation and paste it into new XML files (if needed).

I found it far easier to simply edit the documentation manually with a text editor than try and use the [very limited] GUI tools available - like the LazDE (LCL and GTK versions) and FPDocEdit (as included in Lazarus IDE). Also the indentation of the nodes in the XML files sometimes affect the documentation output as well. Yes Latex and HTML output writers ignore whitespace, but not all other output formats do.

> A "raw text" output (without attributes) would be helpful, in addition > to HTML etc. formats. A text output format exists.

Ah, I didn't notice that.

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.

Good to know :-)

Can namespaces serve the same purpose?

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.

Well, the community might grow when there exists better and nationalized documentation. IMO the procedures and tools for improving the FPDoc documentation are not well known, and translations make no sense without the multi-language display feature :-(

DoDi

I will update the documentation so it lists the available output formats. at least RTF, man, plain text and IPF are currently not described.

I'm not sure I understand what you mean ?

If you're talking about XML namespaces, forget it. Way too complicated and bloated. But maybe you meant something else?

I seriously doubt that, but hope springs eternal, of course :-)

IMO the procedures and tools for improving the FPDoc documentation are not well known, and translations make no sense without the multi-language display feature :-(

Well, we all know pascal, the sources are there. I also had to learn it by diving in, because I inherited the project from its original author.

Michael.

Michael Van Canneyt wrote

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.

Not really related to multi-language, but one thing that puts me off from commiting more documentation improvements is that I cannot see any results ... in a wiki the improvements can be seen imediately, so I can review the work and get more ideas for improving.

I have no idea how often the fpc web documentation is updated, but an automatic daily update would be excelent ...

I commited some improvements for Format maybe some months ago (I added the expected results of the calls), but still no update:

http://www.freepascal.org/docs-html/rtl/sysutils/format.html

Umm, why not generate the help yourself? Instantly see the results, continue editing, generate help, review, repeat... :-)

Generating HTML, IPF, RTF, Text, Man Pages do not require any 3rd party libraries or tools. Generating PDF output requires LaTeX - about a 100-150MB download if your distro doesn't include it as standard.

Due to the latter *huge* requirement, I am busy reworking the RTF output writer. This will at least allow you to generate "working with hyperlinked" RTF output, then simply open it with OpenOffice and export to PDF. Much quicker and no huge downloads required [because OpenOffice / LibreOffice comes standard with most Linux distros - I don't use other OS's].

I have no idea how often the fpc web documentation is updated, but an automatic daily update would be excelent ...

I think Michael's idea is to only publish the latest "released FPC" version's documentation online, or downloadable in PDF form.

And if you didn't bother to read the README.DOCS file in the fpc docs repository, to generate FPC's class documentation, it is as easy as this:

HTML output:
  $ make rtl.chk fcl.chk FPCSRCDIR=/path/to/fpc/source
IPF output (fpGUI & OS/2 INF help)
  $ make rtl.chk fcl.chk HTMLFMT=ipf  FPCSRCDIR=/path/to/fpc/source
CHM output:
  $ make rtl.chk fcl.chk HTMLFMT=chm FPCSRCDIR=/path/to/fpc/source

etc...

Also the indentation of the nodes in the XML files sometimes affect the documentation output as well. Yes Latex and HTML output writers ignore whitespace, but not all other output formats do.

Right, indentation and unlogical blank lines around "<var>" are an issue. That's why I don't want to edit the text parts in the XML files without assistance by approved tools.

DoDi

Hans-Peter Diettrich wrote

Right, indentation and unlogical blank lines around "<var>" are an issue. That's why I don't want to edit the text parts in the XML files without assistance by approved tools.

It's those "approved tools"[1] that are causing all the problems! Hence the reason
I rather write fpGUI's class documentation by hand, with a simple editor like gEdit, or even the IDE's source editor. Using the latter allows me to create and use fpdoc code templates too, reducing the amount of typing I need to do.

[1] Referring to LazDE and Lazarus's built-in FPDoc Editor.

No, I meant exactly the XML namespaces, for which I found methods in the XML classes. But I'm not very familiar with XML, so I leave it to the gurus to work out solutions :-)

*We* do, but nowadays nobody else knows Pascal. IMO the Pascal community will die with our generation, if we (and Embarcadero) don't find ways to recruit new members.

I also had to learn it by diving in, because I inherited the project from its original author.

The lack of translated documentation is a mess, and differing (outdated...) translated documenation also is a mess. That's why I try to provide a documentation managment system, which allows to keep multiple document versions in sync. Such tools exist for general wordprocessing systems, but not for the special formats of the help sources.

BTW, many people have problems with the wiki documentation as well. The lack of an index is annoying, it only encourages unsystematic documentation where nobody can find relevant information without assistance. Content search is almost useless for non-English speakers, which don't know about the right keywords.

DoDi

-1

Most people seriously underestimate the huge amount of effort it takes to document something and keep that documentation up to date. Adding multiple translations to the process is a absolute mammoth task.

That's why mammoth projects (Linux...) succeeded *only* by cooperation of a community :-)

Just take a look at the FPC/Lazarus Wiki. There are many translations, but not nearly as complete as the original English versions.

Just one more indication that there *exists* interest in translating and translated documentation. But all enthousiasm is killed soon by the absence of *any* support tools :-(

I'd say...accept the fact that FPC and Lazarus are English projects (by far the most popular language in many open-source projects) and rather spend your little free time in improving the English documentation.

I *have* much free time, and I'm *willing* to contribute. More oldies (like me) may want to contribute as well, and experience is a big bonus in just the documentation sector.

DoDi

Hans-Peter Diettrich wrote

*We* do, but nowadays nobody else knows Pascal.

That shouldn't really be an excuse. Pascal is so easy to read and understand. Also if you can program in any other language, picking up a new language isn't too hard.

IMO the Pascal community will die with our generation, if we (and Embarcadero) don't find ways to recruit new members.

My son is 2?. As soon as he knows the whole alphabet, that's when his Object Pascal and Test Driven Development training starts. Hey, I need to recruit somebody to help me with fpGUI. ;-)

The lack of translated documentation is a mess, and differing (outdated...) translated documenation also is a mess.

And that is what Michael meant with the community being to small. Everybody is too busy with other things, and documentation is unfortunately one of those very boring jobs.

BTW, many people have problems with the wiki documentation as well.

I'll be the second person to agree with that. Offline help is essential to me, searchable documentation is a must. And over the years I became fussy - I now like well formatted documentation too.

nobody can find relevant information without assistance. Content search is almost useless for non-English speakers, which don't know about the right keywords.

The problem is not only for non-English speakers. I'm an English speaker, and struggle quite often to find anything on the Lazarus wiki. Plus the other problem being that some wiki pages have become so large and even covers multiple topics - so it's like searching for a needle in a haystack.

Hans-Peter Diettrich wrote

I *have* much free time, and I'm *willing* to contribute.

In that case I applaud your willingness to help. :-)

That seams interresting. In my previous attempts to build the docs I ended up with an error for a missing latex dependency or something like that ... I didn't know one can build the docs without it.

Ok, so I issued the command and it seams to have worked! But where are the html files? README.DOCS doesn't say where the output is and neither can I find the html files ... also no error in my console...

Warning: Target ID of <link> is unknown: "getcap"
Warning: Target ID of <link> is unknown: "setcap"
Warning: Target ID of <link> is unknown: "getcap"
Warning: Target ID of <link> is unknown: "setcap"
Done.
touch rtl.chk

Whatever you document in the fpdoc files is immediately shown in the code hints.

Mattias

Where do I find the README.DOCS file?
I use http://svn.freepascal.org/svn/fpc/branches/fixes_2_4 and there is no README.DOCS.

Thanks.

Marcos Douglas

A language consists of 1% syntax, and 99% standard libraries.

The core developers are busy with their hobbies, and the users have to wait for their output. This is not what I understand by efficient cooperation of a community.

That's what I consider cloud computing - guess what weather we'll have tomorrow ;-)

DoDi

Ok, so I issued the command and it seams to have worked! But where are the html files?

Have a look into the docs/html directory?

DoDi

Hans-Peter Diettrich wrote

> Ok, so I issued the command and it seams to have worked! But where are > the html files? Have a look into the docs/html directory?

user-188-33-177-8:fpcdocs felipe$ cd docs
-bash: cd: docs: No such file or directory

Marcos Douglas wrote

Where do I find the README.DOCS file? I use http://svn.freepascal.org/svn/fpc/branches/fixes_2_4 and there is no README.DOCS.

The documentation is in a separate repository. Try this one:

http://svn.freepascal.org/svn/fpcdocs/

I don't remember if trunk in the end is useful or not.

Scripts and more reside in the $lazarus/docs/html folder. When you put the (current) FPC docs into the $lazarus/docs/xml folder, it should be possible to create the entire documentation in one go.

DoDi

Felipe Monteiro de Carvalho wrote

That seams interesting. In my previous attempts to build the docs I ended up with an error for a missing latex dependency or something like that ... I didn't know one can build the docs without it.

You only need latex for the Language Reference, User Guide etc. because they are written in LaTeX. It's not needed for the Class documentation.

Ok, so I issued the command and it seams to have worked! But where are the html files? README.DOCS doesn't say where the output is and neither can I find the html files ... also no error in my console...

It should have created a 'rtl' and 'fcl' directory inside there.

Marcos Douglas wrote

Where do I find the README.DOCS file? I use http://svn.freepascal.org/svn/fpc/branches/fixes_2_4 and there is no README.DOCS.

Where were talking about the FPC docs repository (not Lazarus docs). It can be checked out from the following URL:

http://svn.freepascal.org/svn/fpcdocs/trunk

Hans-Peter Diettrich wrote

Have a look into the docs/html directory?

That is the Lazarus docs directory which uses a very different build system to the FPC docs (which is what we talked about).

For Lazarus documentation you must compile the build_lcl_docs.lpi project found in the <laz>/docs/html/ directory. Then run the following command:

./build_lcl_docs --outfmt html

How come I know this, and I don't even use Lazarus LCL? ;-)

Hans-Peter Diettrich wrote

A language consists of 1% syntax, and 99% standard libraries.

Fair point. But with a good IDE, it can make the learning process much easier using: code templates, code completion, parameter hints etc... Most good IDE's support this lately.

for their output. This is not what I understand by efficient cooperation of a community.

Then you better take that up with the community. ;-)

Ok, thanks. I will try http://svn.freepascal.org/svn/fpcdocs/tags/release_2_4_4/

Marcos Douglas

Ok.
What directory I will should downloading the sources, fpc\doc? This directory is created after a make command... or can be any directory I want?

Marcos Douglas

Marcos Douglas wrote

Ok. What directory I will should downloading the sources, fpc\doc? This directory is created after a make command... ?or can be any directory I want?

Any directory, because if you do the 'make' for the fpcdocs you specify the path the the FPC source anyway. It's all explained in the README.DOCS file.

I have an error (WinXP/FPC 2.4.5):

W:\md\dev\freepascal\compiler\fpcdocs>make rtl.chk fcl.chk FPCSRCDIR=W:\md\dev\f reepascal\compiler\2.4.5
fpdoc --warn-no-node --package=rtl --descr=rtl.xml --content=rtl.xct --hide-pro tected --descr=system.xml --input="-dfpdocsystem -dHASGETHEAPSTATUS -dSUPPORT_DO UBLE W:\md\dev\freepascal\compiler\2.4.5/rtl/win32/system.pp -FiW:\md\dev\freepa scal\compiler\2.4.5/rtl/win32 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/unix -F iW:\md\dev\freepascal\compiler\2.4.5/rtl/inc -FiW:\md\dev\freepascal\compiler\2. 4.5/rtl/i386 -dCPU32 -dHASVARIANT -dFPC_HAS_TYPE_EXTENDED -dHASWIDECHAR -FiW:\md \dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rt l/win32" --descr=objpas.xml --input="-dHASINTF W:\md\dev\freepascal\compiler\2.4 .5/rtl/objpas/objpas.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\ dev\freepascal\compiler\2.4.5/rtl/win32" --descr=types.xml --input="W:\md\dev\fr eepascal\compiler\2.4.5/rtl/objpas/types.pp -FiW:\md\dev\freepascal\compiler\2.4 .5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=strutils.x ml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/objpas/strutils.pp -FiW:\md\ dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl /win32" --descr=sysutils.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/un ix/sysutils.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/objpas/sysutils -FiW:\ md\dev\freepascal\compiler\2.4.5/rtl/inc -FiW:\md\dev\freepascal\compiler\2.4.5/ rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=strings.xml -- input="W:\md\dev\freepascal\compiler\2.4.5/rtl/inc/strings.pp -FiW:\md\dev\freep ascal\compiler\2.4.5/rtl/i386 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/inc -Fi W:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4 .5/rtl/win32" --descr=mouse.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl /unix/mouse.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/inc -FiW:\md\dev\freep ascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" - -descr=keyboard.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/unix/keyboa rd.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/inc -FiW:\md\dev\freepascal\com piler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=cr t.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/unix/crt.pp -FiW:\md\dev\ freepascal\compiler\2.4.5/rtl/inc -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=video.xml --input="W: \md\dev\freepascal\compiler\2.4.5/rtl/unix/video.pp -FiW:\md\dev\freepascal\comp iler\2.4.5/rtl/inc -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\f reepascal\compiler\2.4.5/rtl/win32" --descr=dos.xml --input="W:\md\dev\freepasca l\compiler\2.4.5/rtl/unix/dos.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/inc -dcpui386 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal \compiler\2.4.5/rtl/win32" --descr=sockets.xml --input="-dver1_0 W:\md\dev\freep ascal\compiler\2.4.5/rtl/unix/sockets.pp -FiW:\md\dev\freepascal\compiler\2.4.5/ rtl/inc -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32 -FiW:\md\dev\freepascal \compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --desc r=objects.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/inc/objects.pp -F iW:\md\dev\freepascal\compiler\2.4.5/rtl/i386 -FiW:\md\dev\freepascal\compiler\2 .4.5/rtl/win32 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freep ascal\compiler\2.4.5/rtl/win32" --descr=heaptrc.xml --input="W:\md\dev\freepasca l\compiler\2.4.5/rtl/inc/heaptrc.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/i 386 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32 -FiW:\md\dev\freepascal\com piler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=mm x.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/i386/mmx.pp -FiW:\md\dev\ freepascal\compiler\2.4.5/rtl/win32 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/w in -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=ipc.xml --input="W: \md\dev\freepascal\compiler\2.4.5/rtl/unix/ipc.pp -FiW:\md\dev\freepascal\compil er\2.4.5/rtl/win32 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\f reepascal\compiler\2.4.5/rtl/win32" --descr=printer.xml --input="W:\md\dev\freep ascal\compiler\2.4.5/rtl/unix/printer.pp -FiW:\md\dev\freepascal\compiler\2.4.5/ rtl/win32 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/inc -FiW:\md\dev\freepascal \compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --desc r=typinfo.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/objpas/typinfo.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32 -FiW:\md\dev\freepascal\compil er\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=port s.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/unix/ports.pp -FiW:\md\de v\freepascal\compiler\2.4.5/rtl/win32 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl /win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=getopts.xml --inp ut="W:\md\dev\freepascal\compiler\2.4.5/rtl/inc/getopts.pp -FiW:\md\dev\freepasc al\compiler\2.4.5/rtl/win32 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW: \md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=emu387.xml --input="W:\md\d ev\freepascal\compiler\2.4.5/rtl/go32v2/emu387.pp -FiW:\md\dev\freepascal\compil er\2.4.5/rtl/i386 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\fr eepascal\compiler\2.4.5/rtl/win32" --descr=dxeload.xml --input="W:\md\dev\freepa scal\compiler\2.4.5/rtl/go32v2/dxeload.pp -FiW:\md\dev\freepascal\compiler\2.4.5 /rtl/i386 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal \compiler\2.4.5/rtl/win32" --descr=go32.xml --input="W:\md\dev\freepascal\compil er\2.4.5/rtl/go32v2/go32.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/i386 -FiW :\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4. 5/rtl/win32" --descr=gpm.xml --input="-dVER1_0 W:\md\dev\freepascal\compiler\2.4 .5/rtl/linux/gpm.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/i386 -FiW:\md\dev \freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/wi n32" --descr=graph.xml --input="W:\md\dev\freepascal\compiler\2.4.5/packages/gra ph/src/unix/graph.pp -FiW:\md\dev\freepascal\compiler\2.4.5/packages/graph/src/i nc -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compil er\2.4.5/rtl/win32" --descr=oldlinux.xml --input="W:\md\dev\freepascal\compiler\ 2.4.5/rtl/linux/oldlinux.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/linux -Fi W:\md\dev\freepascal\compiler\2.4.5/rtl/unix -FiW:\md\dev\freepascal\compiler\2. 4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=unixtype.x ml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/unix/unixtype.pp -FiW:\md\de v\freepascal\compiler\2.4.5/rtl/unix -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/ linux -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/linux/i386 -FiW:\md\dev\freepas cal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --d escr=baseunix.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/unix/baseunix .pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/unix -FiW:\md\dev\freepascal\comp iler\2.4.5/rtl/linux -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/linux/i386 -FiW: \md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5 /rtl/win32" --descr=unix.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/u nix/unix.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/unix -FiW:\md\dev\freepas cal\compiler\2.4.5/rtl/linux -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/linux/i3 86 -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compil er\2.4.5/rtl/win32" --descr=classes.xml --input='W:\md\dev\freepascal\compiler\2 .4.5/rtl/win32/classes.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/objpas/clas ses -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compi ler\2.4.5/rtl/win32 -dfpdocsystem' --descr=unixutil.xml --input="W:\md\dev\freep ascal\compiler\2.4.5/rtl/unix/unixutil.pp -FiW:\md\dev\freepascal\compiler\2.4.5 /rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=x86.xml --inp ut="W:\md\dev\freepascal\compiler\2.4.5/rtl/unix/x86.pp -FiW:\md\dev\freepascal\ compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr =dynlibs.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/inc/dynlibs.pas -F iW:\md\dev\freepascal\compiler\2.4.5/rtl/unix -FiW:\md\dev\freepascal\compiler\2 .4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=linux.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/linux/linux.pp -FiW:\md\dev\fr eepascal\compiler\2.4.5/rtl/linux -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/uni x -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compile r\2.4.5/rtl/win32" --descr=math.xml --input="W:\md\dev\freepascal\compiler\2.4.5 /rtl/objpas/math.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/i386 -dFPC_HAS_TY PE_EXTENDED -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepasc al\compiler\2.4.5/rtl/win32" --descr=matrix.xml --input="W:\md\dev\freepascal\co mpiler\2.4.5/rtl/inc/matrix.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/inc -F iW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2. 4.5/rtl/win32" --descr=dateutils.xml --input="W:\md\dev\freepascal\compiler\2.4 .5/rtl/objpas/dateutils.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/objpas -Fi W:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4 .5/rtl/win32" --descr=wincrt.xml --input="W:\md\dev\freepascal\compiler\2.4.5/pa ckages/graph/src/win32/wincrt.pp" --descr=clocale.xml --input="W:\md\dev\freepas cal\compiler\2.4.5/rtl/unix/clocale.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rt l/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=cthreads.xml --i nput="W:\md\dev\freepascal\compiler\2.4.5/rtl/unix/cthreads.pp -FiW:\md\dev\free pascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=cmem.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/inc/cmem.pp -F iW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2. 4.5/rtl/win32" --descr=cwstring.xml --input="W:\md\dev\freepascal\compiler\2.4.5 /rtl/unix/cwstring.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\de v\freepascal\compiler\2.4.5/rtl/win32" --descr=exeinfo.xml --input="W:\md\dev\fr eepascal\compiler\2.4.5/rtl/inc/exeinfo.pp -FiW:\md\dev\freepascal\compiler\2.4. 5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win32" --descr=lineinfo.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/inc/lineinfo.pp -FiW:\md\dev\f reepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win3 2" --descr=lnfodwrf.xml --input="W:\md\dev\freepascal\compiler\2.4.5/rtl/inc/lnf odwrf.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\ compiler\2.4.5/rtl/win32" --descr=ctypes.xml --input="W:\md\dev\freepascal\compi ler\2.4.5/rtl/inc/ctypes.pp -FiW:\md\dev\freepascal\compiler\2.4.5/rtl/unix -FiW :\md\dev\freepascal\compiler\2.4.5/rtl/win -FiW:\md\dev\freepascal\compiler\2.4. 5/rtl/win32" --format=html --output=rtl --footer-date='mmm dd yyyy' A linha de entrada ? muito longa.
make: *** [rtl.chk] Error 255

W:\md\dev\freepascal\compiler\fpcdocs>
----------------------------------------------------------------------- My Win is Portuguese so, the translate this error is "The input line is too long.".

Marcos Douglas

I think this Windows' error. But why this type error do not occurs in ppc386.exe command line?

Marcos Douglas

Marcos Douglas wrote

W:\md\dev\freepascal\compiler\fpcdocs>make rtl.chk fcl.chk FPCSRCDIR=W:\md\dev\f reepascal\compiler\2.4.5 fpdoc --warn-no-node --package=rtl --descr=rtl.xml --content=rtl.xct --hide-pro

....snip...

Thanks for the translation. It seems Windows can't handle such a long command on the command line. Two options I can think of:

1) Try and built RTL docs first, then FCL docs.

2) Reduce the directory path length. eg: place the fpcdocs checkout in c:\temp\ instead of W:\md\dev\freepascal\compiler\fpcdocs

I don't know if these options will help though.

Regards,
- Graeme -

My Win is Portuguese so, the translate this error is "The input line is too long.".

Maybe you are using the wrong make. In windows I always set the path before doing anything in the command line:

set path=path_to_fpc_bin_dir
W:\md\dev\freepascal\compiler\fpcdocs>make rtl.chk fcl.chk FPCSRCDIR=W:\md\dev\f reepascal\compiler\2.4.5

I changed PATH before.
My script:
set myroot=W:\md\dev\freepascal\
set myFPC=%myroot%\compiler\2.4.5
set mybinutils=%myroot%\binutils
set PATH=%mybinutils%\i386-win32;%myFPC%\bin\i386-win32

cd %myroot%\compiler\fpcdocs
make rtl.chk fcl.chk FPCSRCDIR=%myFPC%

Marcos Douglas

I tried, not worked.

2) Reduce the directory path length. eg: place the fpcdocs checkout in ? c:\temp\ instead of W:\md\dev\freepascal\compiler\fpcdocs

I thought putting in fpc docs in fpc\doc\ as it says in README.DOCS but I have others versions of FPC... I'd like to use only one source to documentation and for many reasons of organizations and because W: drive is a external HD, I need to use this path.

Again: But why this type error do not occurs in ppc386.exe command line? There are many many -Fi arguments too.

Marcos Douglas

I don't know how long the given command line is, but the limits for Windows using cmd are as follows:

* up to including Windows 2000: 2047 characters
* from Windows XP on: 8191 characters

The limit when using CreateProcess directly is 32767 characters (max length of a UNICODE_STRING).

Regards,
Sven

Before I forget: the source of this information:
* http://support.microsoft.com/kb/830473/en-us (for the cmd limits)
* http://blogs.msdn.com/b/oldnewthing/archive/2003/12/10/56028.aspx (for the CreateProcess limits)

Regards,
Sven

As I thought... then I may have problems using many arguments (-Fi) for ppc386.exe.
Thanks Sven.

Marcos Douglas

You could pass them using an additional config file.

Create a file, e.g mycfg.cfg and add your "-Fi" entries there (and any other option you'd like to use). Then you call fpc or ppc386 with "@mycfg.cfg" as argument. There the restrictions of Windows don't apply ;)

Regards,
Sven

Very good, but... this tip resolves the ppc386 but not Make. The problem continues with Make to generate the documentation.

Thanks for the tip, anyway.

Marcos Douglas

out of curiosity and because i highly desire local docs, as well, i just attempted this but there seems to be an error or two... i figure the best thing to do is to report it somehow... not sure where or to who but here it is anyway...

C:\freepascal\laz\docs\html>build_lcl_docs --outfmt html --fpdoc c:\freepascal\f pc\2.4.5\utils\fpdoc\fpdoc.exe
Warning! No corresponding xml file for unit forms\forms.pp FPDoc - Free Pascal Documentation Tool
Version 2.4.5 [2011/06/01]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther,

exception at 004722DD:
In 'file:../../xml/lcl//lclintf.xml' (line 5933 pos 7): Unmatching element end t ag (expected "</element>").

C:\freepascal\laz\docs\html>

How come I know this, and I don't even use Lazarus LCL? ;-)

things that make ya go "hummmmm..." :P :)

waldo kitty wrote

out of curiosity and because i highly desire local docs, as well, i just attempted this but there seems to be an error or two...

I would suggest the usual.... report it in Mantis. There is a issue with grids.xml as well, but I don't have a recent lazarus trunk - I mostly use the latest stable branch for day-to-day work.

You can always post a feature request for something similar for fpdoc :)

Regards,
Sven

Support for a project file in fpdoc exists.
I just haven't gotten around to using it in the documentation. It should not be too hard.

Michael.

Nice idea, but before starting work remember that some things are already invented.

One example:
http://www.hl7.org.au/docs/Australian%20Patent%202001100012.pdf

That said, a standard to have a longer look at would be: http://de.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

(assuming you are speaking german, english found there: http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture )

HTH, SCNR and best regards,
Marc

Nice idea, but before starting work remember that some things are already invented.

All that does not help much in managing and editing the FPCDocs.

Roadmap:

I'm just about to show the help entries <element .../> in the XML docs, that have been changed since the last inspection. A last step then would be to show the same element in LazDE for editing (to come). Every difference can be marked as done, and when all differences in one XML file have been processed, the new file can replace the old one in the secondary (backup) directory. For many changes, which can not be processed in one run, it should be possible to save the ToDo list, with all processed sections removed, or to save the backup file with all processed sections updated (to come).

As a first test I use the docs for trunk and 0.9.30, which are not too different. When starting from scratch, e.g. with a translation of the docs, the secondary XML directory is empty and diff only reports missing directories (e.g. lcl, fcl) in the backup. When such an entry is selected, the user is asked whether the directory shall be created in the secondary directory. In the next run diff will report missing files in the created directory, with the option to create skeletons for every selected file (to be implemented). In another run diff will report all the (still empty) entries as different. Now the user can start to translate or create otherwise different versions of the file, marking all processed entries as above.

The tracker has a modular design now, with a general Diff and Document class. From the Diff class currently an XMLDiff class is derived, which removes all non-XML files from the ToDo list. From the Document class an FPDocDoc class is derived, which maps the different lines to FPDoc elements in the XML files, and invokes LazDE for editing entries. Other derived classes can handle other document types, like units or wiki files. Such trackers then can be used to e.g. track changes in the examples directory, so that all (new) example projects can be linked to the related FPDoc entries.

DoDi

I think I'll have to tune my irony emitter a bit ...

My intention was to point out, that there are tools and framework for doing exactly what you are implementing. Having tools ready would free precious developer time for other things.

If those tools are not usable directly it is at least worth a look at the conceptual approach and maybe the xml definition used. It could be helpful to use a standardized file format if you want to give away those doc files and have others do the documentation work.

Since most developers do not like writing documentation and there are trained technical writers for writing manuals and such, it could be worthy.

You arfe right, lazarus' own docs are a special case. But aren't those techniques used for other doc types, e.g. libraries to give away or user programs, the same you are working at?

Having someone else write program manuals isn't a rare case, btdt.

The tracker implementation is ready for use. I only wait for instructions whether it should reside in the Lazarus/doceditor/ directory, or in a new examples/ directory.

DoDi