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

In this part:

Declaration

Source position: line 0
function Format(
  const Fmt: String;
  const Args: array of Const
):String;
function Format(
  const Fmt: String;
  const Args: array of Const;
  const FormatSettings: TFormatSettings
):String;

This information is not in the XML

If you think logically for a moment, you'll understand why this is simply not possible.

I'm surprised you even ask this question.

Michael.

Why does fpdoc require input files, when the description is contained in xml files (desc)?

IMO fpdoc should always create output from the given xml files, regardless of whether according source files are also given.

DoDi

What can I say ? You have a strange sense of logic.

Since the purpose of fpdoc is to document things from pascal source code, for me it follows that it must read the source code first.

This has 2 consequences:

1.
As you can see, the description files do not contain any structural information (type info, function info), just identifiers. The structural information is read from the primary location: the pascal sources.

2.
Doing this means ALL identifiers are allways present in the documentation, and the ones for which documentation happens to be available are documented.

If it were any other way, we wouldn't need source code or XML, we could just use Open Office or Word, that would be equally useful.

Michael.

Because the user should not have to decide this in the first place.

The tool documents pascal code. Hence it must read the code.

Michael.

It is easily possible, of course. When I want documentation created from source files, then I use something like PasDoc. When I create xml files for fpdoc, I expect that these form the base of the documentation. Everything else is unlogical :-(

I'm surprised you even ask this question.

Because it's annoying when I cannot create the content files for rtl and fcl (on Windows), required in building the lcl documentation. I'm missing fpdoc project files for the rtl and fcl, from which documentation can be built without using Make on Linux.

The requirement for perfectly compilable source files, with all options and include files, stands in contrast to building mere documentation. Since fpdoc offers no means to add target specific documentation in the xml files, it should be able to build target-insensitive documentation.

Furthermore, when fpdoc requires package names, why can't it read the source files from the package files, and then look for xml files of the same names in the xml directory of the package?

DoDi

This information is not in the XML

Right, but why doesn't fpdoc leave it to the user, which files should be scanned for detailed information, and for which the description is enough?

DoDi

Hans-Peter Diettrich wrote

It is easily possible, of course. When I want documentation created from source files, then I use something like PasDoc.

That is exactly what fpdoc does too... generates documentation based on source files.

The requirement for perfectly compilable source files, with all options and include files, stands in contrast to building mere documentation. Since fpdoc offers no means to add target specific documentation in the xml files, it should be able to build target-insensitive documentation.

That falls outside the scope of the fpdoc project. It simply generates documentation based on what information you give it.

Of course this process could greatly be enhanced by the help of any IDE that knows about fpdoc. Simply ask the IDE (which already knows the source code files it manages, paths and include paths) to generate a fpdoc build script for your current project or package or library, or it could execute the fpdoc application directly. The IDE can extract from its project settings all the required information to pass to fpdoc.

In fact, this sounds like such a good idea [even if I had to say it myself], I'll be adding it to my experimental IDE.

Furthermore, when fpdoc requires package names, why can't it read the source files from the package files,

fpdoc's reference to "packages" is not the same thing as "Lazarus packages". In fpdoc terms, it is just a way to group a set amount of documentation together. Not everybody that use FPC uses Lazarus IDE - so there simply can't be such a cross-project dependency.

and then look for xml files of the same names in the xml directory of the package?

I would suggest you implement such a feature for Lazarus IDE as I described above, or file a feature required for the Lazarus project.

In our previous episode, Hans-Peter Diettrich said:

This would be a very useful extension, indeed. Unfortunately the RTL and FCL have such irregular requirements, that much work is required to provide a usable command line for the compilation of the according documentation.

Like "./fixdocs.sh" ?

No comment :-(

The tool documents pascal code. Hence it must read the code.

Even if fpdoc is *designed* to document Pascal code, this doesn't imply that it can't be fine with the user supplied xml files.

DoDi

Since the purpose of fpdoc is to document things from pascal source code, for me it follows that it must read the source code first.

This is the purpose of makeskel. Afterwards useful information has to be added to all items, before finally meaningful documentation can be generated.

If it were any other way, we wouldn't need source code or XML, we could just use Open Office or Word, that would be equally useful.

Documentation of course needs a structure, and that structure is fully contained in the xml files. There exists no need for adding further information from the source code, that's more eye candy than essential information.

DoDi

No need to complain, *if* it were so :-(

Unfortunately fpdoc ignores all given xml files, when no corresponding source file is given at the same time. Does a documentation tool serve the user, or has the user to serve the tool???

This would be a very useful extension, indeed. Unfortunately the RTL and FCL have such irregular requirements, that much work is required to provide a usable command line for the compilation of the according documentation.

I would suggest you implement such a feature for Lazarus IDE as I described above, or file a feature required for the Lazarus project.

The Lazarus IDE already includes the FPDoc Editor, which allows to document every identifier in the sources :-)

DoDi

Hans-Peter Diettrich wrote

Unfortunately fpdoc ignores all given xml files, when no corresponding source file is given at the same time.

Isn't that exactly what I said... fpdoc only uses what you supply to it.

Does a documentation tool serve the user, or has the user to serve the tool???

You are more than welcome to extend the tool if you want. I (and probably many others) would also welcome an alternative to Makefile usage for building fpc's docs. I loathe Makefiles.

FCL have such irregular requirements, that much work is required to provide a usable command line for the compilation of the according documentation.

Lazarus IDE already contains all that information, so it's just a matter of extracting the paths and writing the fpdoc command line options to a batch file.

The Lazarus IDE already includes the FPDoc Editor, which allows to document every identifier in the sources :-)

I wasn't referring to editing documentation, but rather "managing a documentation project". Just like you use an IDE to manage a source code project, so too one could use a tool to manage a fpdoc documentation project.

In fact, I remember seeing something like that already. A quick search shows that fpde (included with FPC, but for GTK1 only), and Lazarus's lazde tool have this functionality already. See the Build dialog. You can specify the output format, source and include directories, some fpdoc parameters etc.. You can load and save a documentation project. I have no idea if it is fully implemented, but would imagine it is a bit outdated compared to fpdoc features. I can't compile either fpde or lazde projects at the moment. Maybe you have better luck.

eg:

/opt/fpc-2.4.3/src/utils/fpdoc/fpde/
or
<lazarus>/doceditor/

Hans-Peter Diettrich wrote

This is the purpose of makeskel. Afterwards useful information has to be added to all items, before finally meaningful documentation can be generated.

I personally think makeskel is a terrible idea. It generates a whole bunch of elements making it really hard to find out what is and what isn't documented. It also generates lots of unnecessary elements - obfuscating the xml and documentation more.

contained in the xml files. There exists no need for adding further information from the source code, that's more eye candy than essential information.

I beg to differ. Seeing the signature of a method, procedure, function etc is valuable information to a developer. Not all IDE's or programming editors support "parameter hints", or some developers prefer to keep such feature disabled to speed up the editor/ide. So having such information [method signatures] available in the help is very useful.

Having a inheritance hierarchy is also very valuable, which the current fpdoc XML format doesn't information is
only available when parsing the pascal source code.

No it is not.
I think you should have a good look at the XML files before writing statements like that.

Take an enumerated:
TMyEnum = (One, Two)

It ends up in the XML file as 3 identifiers:
<element name="TMyEnum">
<element name="TMyEnum.One">
<element name="TMyEnum.Two">

All pascal information is lost. Only names exist, without any relations and no type info whatsoever.

From the above XML information you could document equally well

a record

   tmyenum = record one,two : integer end;

a procedure,

   procedure tmyenum (one,two : string);

an enum
TMyEnum = (One, Two)
A class:
TMyEnum = Class

     Function One;
     Property Two
   end;

so from this information, you could never reconstruct the pascal structures it is supposed to document. (and which of course should reside in the docs)

Now, you could "fix" that, of course.
That would require you to copy all information which is contained in the interface section of the pascal file to the XML file.

For example:
<element name="TMyEnum" type="enumeration">
<element name="TMyEnum.One" type="enumerationelement" Parent="TMyEnum"> <element name="TMyEnum.Two" type="enumerationelement" Parent="TMyEnum">

But, copying this information to the XML file would be a) duplicate and thus redundant information.
b) require more work as soon as anything changes in the interface section. and therefor would be - in my eyes - extremely bad design.

That's why the design is as it is and will not be changed anytime soon.

Michael.

Graeme Geldenhuys wrote

...

Graeme, as you are on this issue:

Might this discussion lead to us being able to create a current version of all inf files necessary for docview ?

-Michael

In our previous episode, Graeme Geldenhuys said:

Only the former. Generation of documentation for empty nodes can be surpressed in fpdoc.

True. But that doesn't make it important to be in every fileformat.

Not all IDE's or programming editors support "parameter hints", or some developers prefer to keep such feature disabled to speed up the editor/ide. So having such information [method signatures] available in the help is very useful.

Which is the case now, even though they are not in the XML. Stronger even, if you have an IDE that can't parse the source to get that info, you could develop a fairly simple fpdoc backend to generate a helper file for the IDE.

Having a inheritance hierarchy is also very valuable, which the current fpdoc XML format doesn't information is only available when parsing the pascal source code.

No. You can also get it from the .xct's, which, for the last release, are available in the doc-chm package. The 2.4.4 release is the first that also contains interface inheritance data.

That being said, the .xct format is a bit cumbersome, and I believe Michael already planned to change it to XML.

Michael Schnell wrote

Might this discussion lead to us being able to create a current version of all inf files necessary for docview ?

I am working on some fpdoc fixes for IPF output.

I am also in the process of creating a new fpGUI release - which means I'll generate new pre-built INF help files for all relevant frameworks (RTL, FCL, LCL, fpGUI etc). This should be available for download from SourceForge in the next few days.

Marco van de Voort wrote

> I beg to differ. Seeing the signature of a method, procedure, function > etc is valuable information to a developer. True. But that doesn't make it important to be in every fileformat.

I don't understand your statement about "every file format". Do you meant fpdoc output formats? If so, why would you want limited information in one format, but not in another format?

if you have an IDE that can't parse the source to get that info, you could develop a fairly simple fpdoc backend to generate a helper file for the IDE.

An interesting idea.

No. You can also get it from the .xct's,

Yes, but the XCT files are generated by fpdoc as it parses the source code.

Can you tell fpdoc to not generate an XCT, and then you manually create such a file from scratch using a text editor [which fpdoc can use]? Is so, the latter would be a huge waist of somebody's time.

The Xct contains just enough info to be able to reconstruct a correct inheritance tree. Other than that, it's basically just a list of identifiers and file names. No type .

In our previous episode, Graeme Geldenhuys said:

The bit is that the .XML not having this info is something else then the backend not having it.

Do you meant fpdoc output formats? If so, why would you want limited information in one format, but not in another format?

To avoid duplication of information (make change in pascal source of declaration, and have to make it in the .XML source) of course. Duh!

And this means that the representation of the sources (the declarations) adapt if the FPC parser or fpdoc output generated is improved. Not exactly a theoretic case either.

Or one could stream the entire tree to some XML (just like .xct)

More or less that would make .xct the stuff fpdoc needs, and the secondary (and much bigger XML) some format that IDEs could import for own purposes.

Such schemes are discussible IMHO, if describes a clear case and wants to do the work.

But I haven't seen an actual problem described in this thread, just random bits of problems which till now sound more "invented" then real.

IMHO both Dodi and you should take a step back and describe problems (or maybe even the usecase that is not possible now). Not try to argument on vague principles.

> No. You can also get it from the .xct's, Yes, but the XCT files are generated by fpdoc as it parses the source code.

Sure. And what is the trouble with that?

Can you tell fpdoc to not generate an XCT, and then you manually create such a file from scratch using a text editor [which fpdoc can use]? Is so, the latter would be a huge waist of somebody's time.

I have no idea what you are can build the rtl and fcl via separate makefile targets I guess if you want to processing inbetween, but I think you should start with the actual problem, not with a possible (and terribly hackish) solution.

Marco van de Voort wrote

To avoid duplication of information (make change in pascal source of declaration, and have to make it in the .XML source) of course.

So we agree. :-)

IMHO both Dodi and you should take a step back and describe problems (or maybe even the usecase that is not possible now). Not try to argument on vague principles.

Macro, marco, marco. Please don't jump to such incorrect conclusions. We (You, Michael and myself) are clearly agreeing on how fpdoc should work. I too, don't understand Dodi's logic about fpdoc not needing to parse the pascal sources. I think parsing the pascal sources makes a lot of sense, and fpdoc is indeed doing the correct thing.

but I think you should start with the actual problem, not with a possible (and terribly hackish) solution.

Again, it is very entertaining seeing you go off in your own direction. But I lost you here. I have no clue what you are talking about. But the fact that we actually agree on how fpdoc works (even though you clearly misunderstood my previous messages in this regard), I guess it is not important anyway. :-)

Just this design is very questionable, with regards to useful documentation. My counterexample:

type
   TMyEnum = (one, two);
   TMySet = set of TMyEnum;
...
   property MyProp: TMySet read GetIt write SetIt;

Now we have 7 identifiers, all refering to the essentially same data type. IMO it's only excess work, to document all these elements by themselves, when finally only the property is of interest. Instead I'd prefer a single doc entry, for the property, that also describes the enum elements. All related elements then can be linked to that unique description.

That's why the design is as it is and will not be changed anytime soon.

I don't ask for an change of the design, I only ask for a complete documentation, that includes all elements of the given xml files, even if no source files are given.

DoDi

That's why I mentioned Windows - can you provide equivalent means for Windows, too? On Windows even the makefile doesn't work, and that certainly stands in contrast to the claim "write once, run everywhere".

DoDi

In our previous episode, Hans-Peter Diettrich said:

> That's why the design is as it is and will not be changed anytime soon. I don't ask for an change of the design, I only ask for a complete documentation,

That is the objective.

that includes all elements of the given xml files, even if no source files are given.

That requirement is not part of the fpdoc design nor is it planned.

In our previous episode, Hans-Peter Diettrich said:

Maybe I could yes, with sufficient motivation. IIRC I build the docs just fine with texlive about an year ago. Probably you can follow the above as a general recipe, and build your windows version.

On Windows even the makefile doesn't work,

"doesn't work" is not terribly informative. Maybe you simply don't know windows build systems very well.

and that certainly stands in contrast to the claim "write once, run everywhere".

Please. At least try to come up with believable arguments :-)

That tagline is about what project generates, not whatever theoretical tool that could be used in the project generation.

Moreover you step over the fact very easily that if it doesn't work on Windows, it doesn't necessarily means it is _designed_ not to work on windows.

Third, as said I've played a bit with it an year ago, and I was able to make chm's and html with a bit of testing. So even practically, it is not THAT far from working on windows.

Sure, some parts of the project have a windows maintenance backlog, but I've never seen a sane patch improving the state on windows being rejected. I'm also not aware of any bugreports on this.

On 30/08/2011, Hans-Peter Diettrich wrote: > Unfortunately fpdoc ignores all given xml files, when no corresponding > source file is given at the same time.

[...]

You are more than welcome to extend the tool if you want. I (and probably many others) would also welcome an alternative to Makefile usage for building fpc's docs. I loathe Makefiles.

At least in theory the Makefile can be replaced by fpdoc project(s). It would be a nice feature when fpdoc could also *create* an project file, from a given commandline. This would allow to run Make once, and to use the created project(s) afterwards, on any platform.

For now I only want to remove the code that skips xml files without according source files. In the next step the --descr option should allow for a directory, from which all files can be picked automatically.

This was my idea as well, but I doubt that the Lazarus packages (lpk) contain all information, required to make fpdoc happy. The fcl.lpk contains only a few files, a fraction of the contained units and existing xml files. An rtl.lpk seems not to exist at all :-(

Currently it looks easier to edit an project file manually. Therefore my idea to let fpdoc create a project, in addition or instead of creating the documentation.

I already extended LazDE, for tracking changes to the xml files, so that e.g. translators can know what has changed in the English documentation. But its internal structure is based on single files, no chance to open a package or the like. No idea of fpde, it seems to be not very different from LazDE, and I couldn't yet make it run on Windows.

DoDi

Hans-Peter Diettrich wrote

For now I only want to remove the code that skips xml files without according source files. In the next step the --descr option should allow for a directory, from which all files can be picked automatically.

Automation with fpdoc is not always a good thing. I have already created a command line tool which generates a documentation build script for fpGUI, by scanning the source and xml directories - matching up files. I soon found out that the order of units are important to fpdoc - otherwise you end up with broken links in the generated documentation.

This was my idea as well, but I doubt that the Lazarus packages (lpk) contain all information, required to make fpdoc happy.

Well, that information must be somewhere, because the CodeTools can find all units, include files etc. for a specific platform.

package or the like. No idea of fpde, it seems to be not very different from LazDE, and I couldn't yet make it run on Windows.

I believe the lazde project was simply a clone of fpde - to make it compilable with LCL. I don't think fpde has been maintained in years.

In our previous episode, Graeme Geldenhuys said:
[ Charset UTF-8 unsupported, converting... ]

If you have a small example of that, could you add it to http://bugs.freepascal.org/view.php?id=19144 ?

I also had that feeling, but Michael could not reproduce it.

http://www.stack.nl/~marcov/fpde.zip is a working windows (but GTK) version that I saved at some point.

What I can remember about that is sb showing some initial version of lazde, and in the discussion about it, Sebastian said he was dropping fpgui/fpgtk, and that was pretty much the end of fpde.

IMHO both Dodi and you should take a step back and describe problems (or maybe even the usecase that is not possible now). Not try to argument on vague principles.

Here's my problem:

I cannot create local documentation for LCL, with links into RTL and FCL (...unknown: #rtl...).

This seems to boil down to missing .xct files, which I couldn't create either (on Windows).

>> No. You can also get it from the .xct's, > Yes, but the XCT files are generated by fpdoc as it parses the source code. Sure. And what is the trouble with that?

They could be generated from the xml files as well, or even better: from the collection of generated entries - since links to nonexisting targets are not really useful.

DoDi

Great !
Thanks a lot.
Please keep me posted.

-Michael

Since the current design made the FPC docs what they are, it follows that none of the FPC docs is useful ? Thank you very much.

I don't ask for an change of the design, I only ask for a complete documentation, that includes all elements of the given xml files, even if no source files are given.

This is a contradiction. The part "even if no source files are given."

*IMPLIES*

a change of the design of fpdoc.

If you don't understand that, you haven't understood anything of the way fpdoc works. I can only regret it and will say no more on the subject.

Amen.

Michael.

IMHO the location of where the enum is located is not relevant to the requirement of (or ability to the do without) scanning the source.

Never the less, this could be an interesting feature. If fpdoc could be told (as part of the xml) that the documentation of an element should be embgedded in the parent (enum element, in enum type), or even embedded in a specific other node (a property specified by name, that uses the enum).

Then fpdoc could also automatically adjust all links to those elements. An fpcod-editor/ide could also check that all elements of the source do have documentation (or tell you about new elements that yet need documentation)

It could do this now already. It's just a matter of specifying an alias. A rule like
TMyEnum. -> TMyOtherEnum.
would do it. (the dot meaning that all identifiers starting with TmYEnum must be remapped)

But personally, I don't want the linear XML structure disturbed. I edit the xml files manually, and having a 'tree like' XML then makes it more difficult to edit.

But the fpdoc editor is another matter. You could perfectly adapt lazde to show a tree:

TMyEnum
+- One
+- Two
Same for classes functions, procedures, whatnot. It's just a matter of scanning the element name and creating separate nodes for each part in the dotted name.

I can appreciate that this would be a useful option (and maybe even the default view).

Michael.

I am not too familiar with fpdoc, so maybe something already exists.... but:

I wasn't referring to where the *editor* is showing the information, not even where it is in the xml.

What I meant was:
- TEnum.One / TEnum.One /TEnum
are still each of them documented in their own xml node, exactly as they currently are.

But in TEnum xml node would be an attribute (or a node) declaring: <embed>SomePropertynameUsingTEnum</embed>

An editor may or may not use this to display info in different ways.

But when generating the final help, fpdoc would not generate a separate topic for TEnum. it would embed the documentation in the given other element (does not have to be a propert, could be anything). And links in the documentation would be changed appropriately.

This would allow to document each element on it's own as currently. Yet allow the author to specify that no separate page should be created (which may lead to fragmentation of the docs).

-----------

Anyway, at this point it's only an idea. I have no use for it myself. But the original post *sounded* like this might be desired....

This is what the '<seealso>' is for.

It's not useful to have only 1 "priviledged" <embed> since an enum may be used in many properties of many classes.

In each case, the opposite is already so. The documentation of an enumerated-typed property will normally link to the enumerated type.

Michael.

see also is different

It's not useful to have only 1 "priviledged" <embed> since an enum may be used in many properties of many classes.

that can only be confirmed/decided by the author of the code/docs.

The original mail, that triggered the idea was:

Indicating the desire to have the documentation of the enum exclusively within one property.

Currently that can be done, by just putting it there by hand.

That of course means, should you ever have to link it (which in the avbove case should not be needed / if it was needed it should likely not have been embedded) then the author has to remember to put in the corrected link himself

Putting the enum manually into the property however means more work, if it should later be needed to move to it's own help-page.

In our previous episode, Hans-Peter Diettrich said:

That depends on viewpoint.

$make html ... process_begin: CreateProcess((null), latex user.tex, ...) failed. make (e=2): Das System kann die angegebene Datei nicht finden.

I'm not going to argue on this level, I'm sorry, my time is more precious than that.

Hans-Peter Diettrich wrote

... process_begin: CreateProcess((null), latex user.tex, ...) failed. make (e=2): Das System kann die angegebene Datei nicht finden.

I have never tried to build the FPC documentation under Windows, but if I understood the above error correctly, it is simply trying to execute the 'latex' executable which doesn't exist on your system. Maybe the latex executable is named something different than 'latex' under Windows (eg: latexwin.exe or something). So maybe the Makefile might just need to be tweaked to use a different executable name under Windows.

Just a guess.

Yes. It does so in FPC.

For example

http://www.freepascal.org/docs-html/rtl/classes/tfilestream.create.html

In fact a bad example, because the option is not an enumerated type but simple constants. So let us look at

http://www.freepascal.org/docs-html/rtl/classes/talignment.html

The TAlignment declaration contains a description for all options. Generated automatically by fpdoc, because it knows from the sources that TAlignment is an enumerated, and therefore it automatically prints a short description for all enumerated elements in the definition.

So no need to 'click through'. All is together in 1 page.

Michael.

> On Windows even the makefile doesn't work, "doesn't work" is not terribly informative. Maybe you simply don't know windows build systems very well.

Is this more informative?

$make html
...
process_begin: CreateProcess((null), latex user.tex, ...) failed. make (e=2): Das System kann die angegebene Datei nicht finden.

DoDi

You got it :-)

I assume that this is already implemented.

DoDi

In each case, the opposite is already so. The documentation of an enumerated-typed property will normally link to the enumerated type.

This doesn't make sense, because the meaning of an enum member can vary, depending on the context (class with property). Useful documentation should explain all available options together, and should not require to click through all related declarations, in order to find out what options exist.

DoDi

Hans-Peter Diettrich wrote

$make html [you snipped this essential detail]

Ah, I see the problem now... :)

That was my conclusion as well, but why should any *Latex* tools be called for generating *HTML* output???

Because you are trying to create HTML docs for the Language Reference, User Guide , Programmer Guide and Class Docs. The first three are all written in LaTeX (*.tex) files. Only the Class Docs are written in fpdoc XML files.

If you only want to generate HTML of the Class Documentation (RTL, FCL) then a LaTeX executable is NOT needed. To do this, run the following make command:

    $ make rtl.chk
    $ make fcl.chk

Please read the README.DOCS file for more alternatives for generating documentation.

Here is a more complete command - which I normally use:

  $ make rtl.chk fcl.chk FPCSRCDIR=/path/to/fpc/sources

There is a file called README.DOCS in the documentation directory.

It contains the answers to your questions. Especially line 19 and following.

Idealists as we are in the open source community, we assume that people actually read these files. (But maybe we're just being silly)

Michael.

Nonetheless this one comes close to my expectations.

It e.g. explains why the method name should be mentioned in the short description of the constants, so that the user can know (and jump to) the procedure or method, in which the contant is used (exclusively).

With the downside that this link occurs again in the description of the method itself, and may lead to a different (base) class, when reached from an overridden method in a derived class. Without above insight I had put a definition list into the method description, describing the constants.

Are such fpdoc automatisms documented somewhere[1]?

Every documentation writer should know what is done behind the scene, so that the entries can be structured accordingly. (see above)

I already asked for samples or templates, which can be used to describe elements of the same type. Above links look good for that purpose, for both true enums (TAlignment) and related constants (TFileStream).

A counterexample is TDuplicates
http://www.freepascal.org/docs-html/rtl/classes/tduplicates.html for which it's near impossible to find any details :-( Obviously fpdoc here is fooled by the "TDuplicates = Types.TDuplicates" declaration, so that it can not give the detailed description for Classes.TDuplicates, and furthermore short descriptions for the enum elements seem to be missing in the xml files.

Can you suggest a solution for these problems, so that TStringList.Duplicates will be documented in a useful way?

As you can see in
http://www.freepascal.org/docs-html/rtl/classes/tstringlist.duplicates.html the descriptions had to be *copied*, in order to make them visible there, and all links to the TDuplicates type require to follow further links.

BTW, it would be very nice to have the class members sorted alphabetically, regardless of their type or arrangement in the class declaration. It's very hard to find Duplicates in the TStringList description :-(

[1] I happened to find some hints in fpdoc "5.1 HTML output" description. More and better structured descriptions can be found for "5.2 Latex output". More information should be available, for e.g. the handling of overridden/inherited methods and properties. This may be hidden somewhere else, but IMO should be documented all together in an "How to" fpdoc users guide. When I want to create such an users guide, can you suggest an good place/title in the wiki?

DoDi

On 31/08/2011, Hans-Peter Diettrich wrote:

$make html [you snipped this essential detail]

That was my conclusion as well, but why should any *Latex* tools be called for generating *HTML* output???

DoDi

Hans-Peter Diettrich wrote

BTW, it would be very nice to have the class members sorted alphabetically, regardless of their type or arrangement in the class declaration. It's very hard to find Duplicates in the TStringList description :-(

Use the right tool for the job. :-) fpGUI's DocView (INF help viewer) already does this, and it was very easy to find the "Duplicates" help in TStringList.

I searched for "TStringList", clicked on the Context tab, and saw the following available options:

http://opensoft.homeip.net:8080/~graemeg/docview-1.png http://opensoft.homeip.net:8080/~graemeg/docview-2.png

Thanks, this explains a lot, except *why* the options are so misleading :-(

These lead to different errors, like "could not find 'osdefs.inc' " :-(

I'll retry with the last release version, in the hope to eliminate compiler version specific issues...

Please read the README.DOCS file for more alternatives for generating documentation.

I've read this (and more) before, but obviously could not find the really essential information :-(

DoDi

Adding FPCSRCDIR produces even more funny errors, e.g. *also* in /unix/ipc.pp - when I'm on Windows :-(

DoDi

I'm having difficulties understanding how the text can be misunderstood:

---------------------------------------------------------------------- If you only want the html reference documentation (fpdoc format), type

   $ make rtl.chk
   $ make fcl.chk
----------------------------------------------------------------------

It was put there specially after I received a question exactly the same to yours: 'How can I recreate the RTL reference HTML docs'

Michael.

There is a file called README.DOCS in the documentation directory.

I've read this and many other docs :-)

No, you are not silly - you only read your docs in your own context and background, not how a user will read and understand it :-(

DoDi

Hans-Peter Diettrich wrote

This won't help the users of the fpdoc generated files. There exists no "right" tool for everything and everybody, e.g. I'd prefer the old WinHelp where I can add annotations to every entry.

The latest DocView (in the fpGUI repository) supports inline annotations, bookmarks, searching, dynamically created index, offline help, concatenation of INF help files at runtime, various command line parameters for integration with other apps (eg: IDE's), various user customizations like search highlight color, fonts, encoding, saving help topics to text file etc...

If there is something I left out in DocView that exists in WinHelp, please let me know. So far I think I have many more features than WinHelp had. The only exception I can think of is printing, but that is on my todo list. Alternatively, use the PDF format for printing, it was designed for that (but I like to save some trees, so view help on screen).

But you are correct, no one tool can please everybody. That's why I had a smiley in my previous message.

In our previous episode, said:

I tried to run the full thing "make html", but it failed on unix shellscript in makefile.4ht.

.
.

Graeme, have you managed to move forward with supporting INF files requiring multi-panel views (as used in files from IBM) as discussed some time ago?

Tomas

That's too bad then :-)

Michael.

On Thu, 1 Sep 2011, Hans-Peter Diettrich wrote: > schrieb: > >> There is a file called README.DOCS in the documentation directory.

.
.

.
.

This should be indeed clear enough. Possible improvements coming to my mind would be skipping the '$' sign at the beginning (as that is specific to Unix platforms and not really part of the typed command anyway) and also mentioning the assumed prerequisites for the command above to work properly (e.g. either starting this command from the full fpcbuild export or having the source files pointed to by some environment variable).

Tomas

Tomas Hajny wrote

mind would be skipping the '$' sign at the beginning (as that is specific

That is simply a "generic term/symbol" to indicate that what follows should be typed in at a command prompt. We can't use bold or italics or a different font, as is used in other types of rich documents, to explain what parts of text means "type this in as is at a command prompt".

properly (e.g. either starting this command from the full fpcbuild export or having the source files pointed to by some environment variable).

Read the rest of the README.DOCS file. It's all there!

Tomas Hajny wrote

Graeme, have you managed to move forward with supporting INF files requiring multi-panel views (as used in files from IBM) as discussed some time ago?

Yes, I have a offline branch that works somewhat with that. The implementation is not very good because fpGUI doesn't support a MDI interface yet. So I had to achieve the same effect using non-modal popup windows. I don't really like this solution, so would rather implement MDI support first, before DocView gets further attention regarding multi-window INF files.

It the mean time, DocView has received a lot of other attention. The RichView component, used to display the help content, has gained a speed increase of some 10-20 times faster that before. Memory usage has dropped by around 50%, I improved text wrapping and painting, corrected scrollbar synchronization, as well as some memory leak fixes have been applied.

At the moment I'm readying the 0.8 release of fpGUI, which should happen over the weekend. Then work can begin on MDI and MiG Layout Manager support, which are scheduled for the 0.9 release early next year.

I changed the text to:

If you only want to generate the RTL and FCL reference documentation in HTML format, starting from the fpdoc XML descriptions, then the following 2 commands should be enough:

   $ make rtl.chk
   $ make fcl.chk

The prerequisites are present under "General Settings"

Michael.

Well, this is exactly something that may easily be seen as part of one's context/background. It is surely not something generic for most Windows-only programmers. You don't need to clarify the meaning to me but rather consider whether this understanding applies to all others (OK, mostor at least most).

.
.

Correct, sorry, my fault. :-( Putting some kind of a forward reference to the General settings chapter before the make command wouldn't hurt, but that's indeed no excuse for not reading up to the end right away.

Tomas

> I'm having difficulties understanding how the text can be misunderstood: > > ---------------------------------------------------------------------- > If you only want the html reference documentation (fpdoc format), type

What's this "fpdoc format", and what's "html reference documentation"? I need no help on HTML...

Yes, the prerequisites seem to be essential for running the Makefile.

DoDi

Fine.

The prerequisites are present under "General Settings"

Prerequisites should include the tools, which may be required for certain operations (Latex...), and perhaps other config files for the determination of the target etc., required for parsing the source files.

There must exist some reason, why
make rtl.chk
leads to other errors than
make rtl.chk FPCSRCDIR=<current dir>
with Windows related files and directories in both cases, but additionally with Linux related items in the second case. For this issue the Makefile may need an update, to make this different behaviour disappear (probably easier than to explain why...).

DoDi