[fpc-devel] fpdoc content syntax suggestion

[Mattias Gaertner]

On Fri, 09 Jul 2010 09:16:43 +0200
Graeme Geldenhuys <graemeg.lists at gmail.com> wrote:

>[...]
> Here is a simple example.
> 
> --------------------
> < p >Paragraph one.< /p >
> < p >< b >Note< /b >< br >
> Paragraph two goes here.
> < /p >
> < p >Paragraph three goes here.< /p >
> --------------------
> 
> Just look at the amount of tags for something so simple. We don't write
> emails like that, or any other text for that matter, so why must we burden
> the documentation writers to do so.
> 
> Why couldn't the above be something like this... a simplified "light" markup.
> --------------------
> Paragraph one.
> 
> [b]Note[/b]
> Paragraph two goes here.
> 
> Paragraph three goes here.
> --------------------
> 
> * Tags use the square brackets, so as not to interfere with XML tags.
> * Hard line endings, are considered the beginning of a paragraph.
> 
> 
> Or use something as simple and popular as Creole or WikiText.
> --------------------
> Paragraph one.
> 
> *Note*\\
> Paragraph two goes here.
> 
> Paragraph three goes here.
> --------------------
> 
> * A blank line denotes a end of paragraph.
> * The \\ denotes a forced line break.
> * The * before and after a word denotes bold text.

+1
Although I don't know how attributes like /var should look like. Can
you create a full list of supported tags?

 
>[...]
> So would the FPC team consider such a change in fpdoc? Obviously I will do
> most of the work, as I am suggesting the change. If you guys don't agree,
> I'll probably still do the work by forking fpdoc (which I don't really want
> to do), to fulfill my own needs and some of the open source projects I work
> with (fpGUI and tiOPF use fpdoc a lot). Mixing HTML tags inside XML or the
> documentation content is just not the right way to go. fpdoc is great, I
> simply want to make it even better.

It should be possible to still read old xml pages. Maybe add an
"dataencoding" tag at the beginning of a fpdoc format?
And we need a converter.
I don't think a mix of different formats in one file is needed.

 
> References
> ==========
> AsciiDoc:   http://www.methods.co.nz/asciidoc/
> Creole:     http://www.wikicreole.org/wiki/Creole1.0
> My OP wiki: http://opensoft.homeip.net/wiki/wiki.cgi?p=Main-Page


Mattias