Thanks for the reply. I looked closer into the docbook->htmlhelp gen for chm generation.. This gets me to result close to where I can wrap soem additional code on top and replace doxy. But I have 2 issues: need control where to chunk and control the file names of the chunks.
The reasoning is that for html help, we need to have an [ALIAS] section (in the hhp) that will look like: IDH_FuncName1=file1.html IDH_FuncName2=file2.html .... I also want each function (functioname) to be split into its own separately chunked-up html file (e.g. functioname.html). This makes it easy for external program to directly open help for a function, by just knowing the function name. Here, i see that some control of chunking but seems only a choice for a different FIXED section level than default 1 can be made: http://www.sagehill.net/docbookxsl/HtmlHelp.html#HHContextHelp But how can i control that to chunk, before any section header that I need? Also how do I control the name of the chunk? Looks like i need to pass some args down to xsl; do I pass e.g. use.id.as.filename ? Is it via: --xsltproc-opts ? And more important how do I set "id" or "xml:id" attributes in asciidoc txt? Would like to keep changing that name with each function. Where in asciidoc txt do I enter things like below (suggested in same doc, for context sens help)? (without breaking my pdf generation from same asciidoc file) <chapter id="install"> <?dbhh topicname="IDH_opt_installation" topicid ="1234"?> <title>Installing optional components</title> Thanks, from an otherwise experience programmer who is unfort rather lost in xsl space.. tm On Jun 7, 2:43 am, Lex Trotman <[email protected]> wrote: > 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 > > athttp://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.
