doxygen/robodoc functionality

[Werner LEMBERG]

Folks,


after reading the documentation, I like pandoc a lot, and I'm just
starting to use it, so please forgive my newbie questions.

For a project, I would like to write the documentation in pandoc's
markdown (mainly a users' guide). However, for the library functions,
I would like to put the markdown stuff into a C header file (using a
structure similar to doxygen or robodoc[1]), and this documentation
should be (a) converted to a man page, and (b) included into the
users' guide.

Any idea how to proceed? A quick internet search hasn't shown
something relevant, but maybe I've just used the wrong keywords...


Werner


[1] I've looked at both programs, and they don't really fit my need.
Well, maybe they do, but pandoc looks superior to me for my
purposes.

[Peter Wang]

Post by Werner LEMBERG
Folks,
after reading the documentation, I like pandoc a lot, and I'm just
starting to use it, so please forgive my newbie questions.
For a project, I would like to write the documentation in pandoc's
markdown (mainly a users' guide). However, for the library functions,
I would like to put the markdown stuff into a C header file (using a
structure similar to doxygen or robodoc[1]), and this documentation
should be (a) converted to a man page, and (b) included into the
users' guide.
Any idea how to proceed? A quick internet search hasn't shown
something relevant, but maybe I've just used the wrong keywords...

Depending on how elaborate you want it, you could use a special comment
syntax like NaturalDocs:

/* Function: foo
* Place markdown here.
*/
void foo(int a, int b)
{

then rely on your coding conventions so that you don't need a proper
parser to extract the text and type signature. Then you can generate
the pages to be passed to pandoc.

The next thing to take care of is probably cross-references. For HTML
you can generate a file containing:

[foo]: module.html#foo

then you can reference it by simply writing "[foo]". For other output
targets it's more complicated.

Peter

[Werner LEMBERG]

Post by Peter Wang

Post by Werner LEMBERG
For a project, I would like to write the documentation in pandoc's
markdown (mainly a users' guide). However, for the library
functions, I would like to put the markdown stuff into a C header
file (using a structure similar to doxygen or robodoc[1]), and this
documentation should be (a) converted to a man page, and (b)
included into the users' guide.

Depending on how elaborate you want it, you could use a special comment
syntax like NaturalDocs: [...]

Thanks for the hint. We've written something similar for FreeType (in
python) to extract comments which are then converted to HTML.
However, I have hoped that such an extension module already exists for
pandoc, avoiding the dependency on still another program.

Looking at pandoc's scripting page it seems that a solution shouldn't
be extremely difficult. Unfortunately, I have zero experience with
Haskell... On the other hand, since I'm using automake which needs
perl, a solution might be to write something in perl to extract header
comments to get plain pandoc input.


Werner