I started looking at asciidoc for the generation of technical manual
+doc for a library of programming functions (few 100 of them). So far
read all docs and looked at samples and searched this list a bit but I
am unsure about how to do this.
So far, it does not look to me that asciidoc is designed for html
documentation where html pages are split up in the way i decide - and
looks more well suited for "monolithic" (single) document generation.
(or large html page). I could be wrong, but pls do prove me wrong by
looking at my case below!
The functions (they are functions in C) are grouped in higher groups;
looks something like this:
Top page
List of Functions
Function Group A
Function func1( a, b, c )
Function func2( a2, b2 )
Function Group B
Function SubGroup B-1
Function func3( a3 )
Function func4( a4, b4, c4 )
Function SubGroup B-2
General Information
How to call functions from your code
How to install the library
Linux install
Windows install
I like and it is easier so to write doc where each function (func1,
func2, ...) is in its own .txt file; it should also generate a single
html file for html output; and each func needs to be in a separate
page(s) for pdf manual. Also each page that captures a group of
functions has some text about the group and needs to link to each one
of the functions in the group (plus its parent).
Each function needs to have a "See Also" section; so it can easily
refer to other function or doc page. And also its parent group page.
I used doxygen for this and worked to a degree; but there are some
limitations and missing functionality; plus the output is not as nice
as asciidoc.
I am not sure how to do below with asciidoc, any suggestions/pointers
from people
* Is there any way to model a "hierarchical grouping" in asciidoc?
I.e. in each function txt file, can I just mention the group it is
part of, so function group doc automatically includes pointers to all
the functions (and its parent). Or do I have to drive all this all
manually? Grouping and easy referencing will save a lot of time.
Would like to avoid each time I add a new function doc page to have to
also manually populate its parent/group page. This part is done
automatically by doxygen.
* "See Also" section; per function or any other page; how can i link
to other functions or other doc pages (including parent group) by just
using some cross-ref tag? This is not obvious to me; doxygen processes
all the files in one shot and allows cross-ref labels/tags between
pages. So how do I make cross refs between *separate* asciidoc txt
(and html) pages?
* Is there any way to support simple search in the html pages -
similar to that in doxygen? I.e. type a keyword in a box (e.g. a
function name) and find and show the function. Can the asciidoc
Glossary section be used for that index?
Note, for pdf output, I will need to link all pages (via :include: ?)
into one processed output. But for html (and hence .chm, which we also
need) we need pages to be separate.
Thanks for any suggestions on how this can be done the easiest way.
--
You received this message because you are subscribed to the Google Groups
"asciidoc" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/asciidoc?hl=en.
