In my review of the fpdoc project option some questions popped up. The most important question: should fpdoc be usable for creating online help only, or should it also allow users to create offline documentation on their local machine? When a user can create documentation files for local use, the configuration and directory structure of the current machine deserve some considerations.

Currently the commandlines are created by scripts, with predefined compiler options, at least for the RTL units. How portable are these options, with regards to different platforms? In detail the -Fi options?

What's the purpose of --ostarget and --cputarget? These options are documented as "for the scanner", presumably for conditional compilation. Are these options valid (or required), so that the input files are processed in the same way and with the same include directories, regardless of the machine running fpdoc? In this case all related fpdoc options have to be saved in the fpdoc project files.

The --import options specify both the locations of the content files, of related packages, as well as the link target locations (prefixes). This requires a fixed directory structure, or else the content files can not be found, and HTML links may be broken. Such a fixed directory structure can be assumed only for the RTL and FCL documentation. The LCL documentation instead will reside in an unrelated directory branch, so that all references to the FPC documentation depend on the directory structure of the user machines.

This doesn't look very practicable to me - how would fpdoc or any script find the location of the FPC documentation, on every single machine? Or will the user be responsible for providing the locations of all dependent packages documentation? Lazarus already requires to configure the paths to all documentation source directories, for use by the FPDoc Editor.

Should we introduce a single (HTML) documentation directory, on every target machine, where *all* package documentations can reside side-by-side, with fixed relative references? Or should HTML documentation be deprecated, in favor of more position-independent CHM files? (dunno whether this would really help).

DoDi

In our previous episode, Hans-Peter Diettrich said:

In my review of the fpdoc project option some questions popped up. The most important question: should fpdoc be usable for creating online help only, or should it also allow users to create offline documentation on their local machine?

Maybe.

When a user can create documentation files for local use, the configuration and directory structure of the current machine deserve some considerations.

Maybe

Currently the commandlines are created by scripts, with predefined compiler options, at least for the RTL units. How portable are these options, with regards to different platforms? In detail the -Fi options?

Not. But usually in such cases this is solved by mostly using relative dirs and a few substitutions.

The project file should hold the bulk of the options. Not necessarily all.

True. This is one of the main problems of using plain HTML, and has existed for e.g. the plain html docs of the textmode IDE since forever, and is one good reason to use CHM.

The only good solution is using a help using a local webserver (then the webserver hierarchy and the filesystem hierarchy can be decoupled) Newer helpsystems of microsoft go that way, but this is IMHO a lot of pain, support and management wise.

This doesn't look very practicable to me - how would fpdoc or any script find the location of the FPC documentation, on every single machine?

Not all options are possible with all output formats. Some output formats (like plain html) have limitations. There is nothing fpdoc can do there.

I don't see plain html as a valid target for offline help. I reserve that for CHM. With the textmode IDE, the plain html was nothing but pain.

From an older post here a typical list with problems:

- it is uncompressed -> huge on disk. Try to keep it in archive -> non standard.
- it is not an archive, people can mess with it to easily or accidentally,
- needing a lot of checks in the browser for all kind of weirdnesses. Both on filelevel (locking, renaming) as to see that the content is complete.
- On slow systems it takes minutes to unpack large plain html zips.
- Doesn't shield you from the Idiosyncrasies of the various files systems. (8.3, LFN, forbidden chars)
- there is no standardized way of providing an index, TOC etc. While plain html is considered a standard, everything that is additional to make it a helpsystem is not.
- (The format of html is too large. I would have prefered a type that would not allow so much syntax. However CHM as the same problem as it is essentially compressed + indexed html)

They are not platform specific.

These options simply add some defines in the scanner. They have no other effect.

Explain why you think this requires a fixed directory structure ?

Obviously, the user is responsible for providing the locations.

You are of course free to set up a system to register such locations; I do not consider it the job of fpdoc. You can create a shell around fpdoc that handles all this.

These are not fpdoc questions; These are questions on how you organize your work.

It seems to me you are reading too much in fpdoc. fpdoc takes some input files and produces output. No more, no less.

All the questions you ask have more to do with
'how do I organize my work with fpdoc'
rather than with
'how should fpdoc function'.

Michael.

In our previous episode, said:

> will reside in an unrelated directory branch, so that all references to the > FPC documentation depend on the directory structure of the user machines. Explain why you think this requires a fixed directory structure ?

In plain html, the crossreferences are a problem. Afaik this is currently solved by assuming all modules are in the same dir ( $basedir/rtl $basedir/fcl etc) and generating crossreferences such with relative paths

(so rtl/xxx/yy.html referencing fcl/zzz/ooo.html is done by generating a link to ../../fcl/zzz/ooo.html )

But this is an html format problem, not a fpdoc problem.

I thought the cross-references are done based on the location of the cxt file, and all links are make relative to this location ?

Michael.

You should understand the problems of Windows users. Until now they cannot produce local documentation, due to several bugs in the Makefiles, fpdoc and related tools. This is a bad situation for documentation writers, which cannot test their work thoroughly.

That's why I see a big improvement in ready-made fpdoc projects, which do not depend on Makefiles and other scripts or tools. It's not really hard to update an XML file in any editor, to supply e.g. missing include files; the same requires many more skills, when a Makefile has to be edited.

When in the next release we can provide fpdoc projects for the RTL, FCL and LCL documentation, then the users will need some documentation about creating local or customized documentation. As you may see from my many questions, using fpdoc is not really easy, right now :-(

DoDi

In our previous episode, said:

Sorry, forget it, I was thinking about the latex docs, not the fpdoc. I would have to look it up what it does.

I fail to see the problem here. fpdoc can already generate online and offline help formats. HTML for online usage, and CHM, INF, TXT, MAN and PDF for offline usage.

The --import options specify both the locations of the content files, of related packages, as well as the link target locations (prefixes). This requires a fixed directory structure, or else the content files can not be

Correct, each developer organizes there files in there own way. What works for me, might not work for you. So there is no way fpdoc can simply assume or automatically figure out each developers file organization style.

fixed relative references? Or should HTML documentation be deprecated, in favor of more position-independent CHM files? (dunno whether this would really help).

There is a valid use-case for plain HTML output, so I don't think it should be deprecated.

Marco van de Voort wrote

I don't see plain html as a valid target for offline help. I reserve that for CHM.  With the textmode IDE, the plain html was nothing but pain.

Indeed. HTML lacks a TOC, Index, searching etc. Plus it is verbose and HUGE in terms of disk space. Similar applies to PDF. In the case of PDF's, you have beautifully formatted documentation, but the viewers tend to be damn slow, and slow at searching, and there no easy way to support "context sensitive help" with PDF's. For this reason there are specialized fpdoc output formats. HTML for online viewing, CHM & INF for fast offline viewing (with a TOC, Index and searchable) etc.

I'm also working on a new ePub output format - specialized for tablet usage.

This doesn't work for CHM output, so that --import expects both a reference to the content file and a link prefix, where the link prefix differs between HTML and CHM output (see help on --import).

Now it IMO is an fpdoc (project) problem, when the required packages are *not* listed in the project. Once the required imports are part of the project, fpdoc can check for the related information, and issue an error message when something's missing in the command line or in the target directories. An fpdoc project could include entries like <import package=rtl content="../rtl.ctx" htmlprefix="../rtl" chmprefix="..."/>
which will typically reduce to
<import package=rtl/>
because everything else can be derived from the context file reference, which *must* be present in the --import command line option.

A user then can write its own batch file, like
fpdoc -p=mydoc.xml --import=<myrtl.ctx> --import=<myfcl.ctx> --output=<whatever>

DoDi

The only conclusion I am making from this is that I should switch the documentation generation to use a project file, due to a limitation of the command-line in windows. Other than that I haven't heard anything which makes me conclude that there are problems in fpdoc itself.

Michael.

Now you hear some, most probably from the first user of fpdoc on Windows ;-)

BTW, I found more bugs in the code, when I moved the CreateDocumentation method into TFPDocProject.

DoDi

Hans-Peter Diettrich wrote

Now you hear some, most probably from the first user of fpdoc on Windows ;-)

I use fpdoc under Windows without problems. Though mostly for generating documentation for my own projects, not FPC ones. I also use a console utility program with TProcess to execute fpdoc, and not the command line directly. My console utility app can also generate scripts/batch files to generate the documentation (but then you hit the command line size limit under Windows).

Please report bugs in the tracker.

Michael.

Thank you, Graeme.

You confirm what I suspect.

Michael.

Hans-Peter Diettrich wrote

Now you hear some, most probably from the first user of fpdoc on Windows ;-)

If you were, then this file would not exist:

http://svn.freepascal.org/cgi-bin/viewvc.cgi/trunk/docs/html/build_html.bat?root=lazarus&view=log

I have built html docs in windows without any issues around 2 years ago. I rarely build the docs in Windows nowadays, so I don't remember the details.

Examples which *happen* to work are not a proof for the absence of bugs.

I cannot separate the observed errors into fpdoc and Makefile specifics, because I don't understand the logic in the documentation Makefile and in the fpdoc parser and generator. I only can hope that we don't end up in an deadlock, where the Makefile authors say that it's a problem of fpdoc, and the fpdoc maintainers say that it's a problem in the Makefile.

DoDi

I (tried to) use DocView (*.inf files) for local help. Seems very promising.

-Michael

Graeme Geldenhuys wrote

I'm also working on a new ePub output format - specialized for tablet usage.

Never heard of same. Is this supposed to replace *.inf ?

-Michael

Michael Schnell wrote

Never heard of same. Is this supposed to replace *.inf ?

No, ePub is a specialised HTML/XHTML archive format. A single file used for electronic books. It is most often used on tablet pc's, smart phones and e-Book readers like Amazon Kindle.

http://en.wikipedia.org/wiki/EPUB

The nice think about ePub is that you can change fonts, font size, background color etc, and the content is sized according to the device you are reading on. DocView does all this too. ;-) You do get eBook readers for PC's too. eg Opera web browser has such a plugin, or FBReader.

My main problem at the moment is again the Latex format. It is very hard to convert LaTex to any other format (and still look good). This was the main reason I wanted to implement ePub support. But maybe a better idea is to improve the LaTex-to-PDF (but in A5 page size. A5 size FPC docs (the language reference, programmer guide etc) read much easier on example the iPad - compared to the A4 (default) size.

In our previous episode, Graeme Geldenhuys said:

My main problem at the moment is again the Latex format.

Manipulate the generated HTML?

Probably doable, but if margins get smaller, you get into trouble with verbatim output (e.g. listings). Probably will have to tweak the font of that, but I don't know if that yields usable output

Marco van de Voort wrote

In our previous episode, Graeme Geldenhuys said: > My main problem at the moment is again the Latex format. Manipulate the generated HTML?

Yes, I was thinking in that same direction.

I have already created A5 versions of the LaTeX docs. There are some minor issues I still need to sort out like the margin on one side was bigger than the other. But overall, A5 was much nicer to read than A4 ones. I'll see if I can wrap up the changes into some patch so that it is easily switchable between A4 and A5.

Graeme Geldenhuys wrote

Yes, I was thinking in that same direction.

My son some time ago wrote a HTML parser / Writer that creates a linked List of objects (similar to the XML parser) .

Maybe this could be helpful.

-Michael

Michael Schnell wrote

I (tried to) use DocView (*.inf files) for local help. Seems very promising.

I've just released fpGUI v0.8. With that release comes pre-built binaries for DocView, and pre-built documentation in INF format. You can download them from the following links.

http://sourceforge.net/projects/fpgui/files/fpGUI/0.8/ http://sourceforge.net/projects/fpgui/files/fpGUI/Documentation/