[fpc-devel] fpdoc content syntax suggestion

[Marco van de Voort]

In our previous episode, Graeme Geldenhuys said:
> Op 2010-07-09 09:51, Marco van de Voort het geskryf:
> > 
> > I think losing full layouting capabilities (even though sometimes
> > problematic) would be an huge loss.
> 
> Could you give an example? Do you mean you hard-code HTML tags inside the
> <descr> and <short> contents? This is exactly what I am trying to prevent.

Yes.
 
> The documentation should have it's own markup syntax, and the backend
> (HTML, IPF, LaTeX etc) should translate that markup to its native syntax
> and formatting.

It could be an option for people that want everything to be wholly portable. 
It should not be forced.  There should be a passthrough option for people
that only use backend (be it latex or html or whatever), so that these don't
get forced to use some politically portable lowest common denomitor subset.

Maybe this should be typed though (iow you need to specify what the contents
is), becuase that can help the parser that substitutes the "own" tags.

> > Specially because now we are also think
> > about using fpdoc for normal helpfiles.
> 
> I thought about that as well, and fpdoc wasn't designed for that.

Michael said he saw some possibilities. (since it can add arbitrary topics)

> My thinking was that whatever new syntax (for the help content) is used,
> the parser for that could be reused in a new "general application help"
> tool, which also supports various output formats.  There could possibly be
> some overlap (common code) between that new documentation tool and fpdoc,
> but that should rather become a task of refactoring, once both tools
> exist.

There has been nothing yet decided. Michael saw some possibilities for
lazdoc/fpdoc, nothing more. 

But whatever solution is chosen, I would allow people to use the full
possibiltiies of the backend, and import/reuse fragments they already have
in the backend language.
 
> Another since step forward will be a WYSIWIG editor for the help content -
> completely hiding the markup syntax from the help author, but that fall
> outside the scope of FPC.

More trouble then it is worth IMHO.