[fpc-devel] FPDoc projects future

[Marco van de Voort]

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.
 
> 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 project file should hold the bulk of the options. Not necessarily all.
 
> 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.

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.

> 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).

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)