On 7 June 2012 08:58, techmagos <[email protected]> wrote: > 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!
Hi, You are right, asciidoc is not really targeted at reference manuals of the type you describe. There are many issues with such systems that make a bespoke solution more appropriate. As you note not even doxygen works completely. I will note my thoughts 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). The problem with this is that when its a standalone page the function description is at a different level than when it is encapsulated within the whole document. So you can't use headings to define document sections since their level would change, but headings are the things that PDF toolchains use for tables of contents. You therefore must always process the text files as part of the whole document. You can still get chunked HTML from the appropriate toolchain. > > 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. Links work fine, even to other html files, but you do have to know their URLs. > > 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. Such automation is not in the scope of asciidoc, as I said the whole group needs to be processed as one. You can of course use the include macro to combine text files from a master document. > > * "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? Hyperlinks. > > * 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? Keywords in boxes would need code you provide. asciidoc generated HTML can include user defined javascript, I'm not sure about chunked. A toc or glossary could certainly be used as an 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. As I noted above, you have to process the whole lot together then generating .chm (see a2x). Cheers Lex > > > 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. > -- 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.
