Hi,

What is the smallest, most compact system for software documentation that can handle text, graphics, and preferably mathematical formulae as well? I am looking for something that can eventually be presented on a form, documenting not just what my code does, but, more importantly, the "why" arguments that led me to choosing just that algorithm. fpdoc? Delphi-Markdown (https://github.com/grahamegrieve/delphi-markdown)? AsciiDoc(tor)? OpenDocument format?

wolf

LaTeX ?

I am looking for something that can eventually be presented on a form, documenting not just what my code does, but, more importantly, the "why" arguments that led me to choosing just that algorithm. fpdoc? Delphi-Markdown (https://github.com/grahamegrieve/delphi-markdown)?

Delphi markdown is not a documentation system.
It just changes markdown to html.

AsciiDoc(tor)? OpenDocument format?

Same arguments apply. They are just formats for making up text ?

Maybe I misunderstood what you mean by 'software documentation'.

Michael.

IMO you need:
- Latex files (with formulas)
- lib which can render latex to HTML
- lib which can show HTML on a form (several exist for fpc)

Alexey

Michael Van Canneyt wrote

LaTeX ?

The original poster was vague about what he wants, but he did mention "compact" - so if we assume a compact documentation system, then LaTeX is not it. Installing LaTeX takes up about 200-400MB depending on the system. ;-)

But for overall "pretty looking PDF's" with mathematical formulae it is hard to beat LaTeX.

Regards,
Graeme

Thank you, Alexey, Graeme, Michael, for a share of your experience. If I understand you aright, what I want to do is best done as a two-step process: firstly write the documentation in an editor capable of saving it as HTML, then as a second step render the HTML file onto a Lazarus form.

As an editor, I'd prefer LibreOffice, since I am familiar with it. My experience with LaTeX is limited, as I recall it has quite a mind of its own when it comes to deciding what to render where - using it would mean abrogating much of the control over final layout that LibreOffice offers. And layout is important when documenting thoughts and thinking.

Thus, there remains rendering HTML onto a Lazarus form. Have you any suggestions on which component to use?

wolf

Wolf wrote

As an editor, I'd prefer LibreOffice, since I am familiar with it. My experience with LaTeX is limited

Having extensive experience with both for many years I can say that with some decent preparation work you can generate documents with LibreOffice that rivals LaTeX output and layout. I have created such document templates with OpenOffice a couple years back. I can search my hard drives and see if I still have those around, if that might help.

I remember the OpenOffice organization had brilliant documentation and guides in generating such document templates, but as the LibreOffice project gain popularity the websites hosting the original OpenOffice documents and guides disappeared one by one.

On a side note:
OpenOffice (and I guess now LibreOffice) also have impressive mathematical formulae support. I wouldn’t instantly dismiss it. We used those in a prior company I worked for.

Have you any suggestions on which component to use?

From what I’ve seen [2-3 years ago] there is none that really does a good job.

Regards,
Graeme

I can agree, I have seen very impressively formatted documents done in LibreOffice/OpenOffice/Microsoft Word. At the same time, the majority of technical documents seem to be meant for screen-based consumption. In that case the viewing options for the listed formats can be less attractive than they otherwise might be.

> Have you any suggestions on which component to use? From what I’ve seen [2-3 years ago] there is none that really does a good job.

I would suggest using Sphinx, http://www.sphinx-doc.org/en/stable/, the software package that Python uses to generate its documentation. It can be adapted to other languages and I worked with a project that uses it with an Object Pascal codebase.

With most software packages in this vein, the possibility of generating images that are rendered from LaTeX exists. However, you need an installation of the same to do this.

Cheers,
R0b0t1