On 8 June 2012 10:15, techmagos <[email protected]> wrote: > 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 ?
Yes you pass xsl options using xsltproc-opts. As to which options to pass, toolchain details are mostly beyond the scope of this list, if someone knows they will tell you, but you will probably more likely to get help on the appropriate list. > 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. http://www.methods.co.nz/asciidoc/userguide.html#X41 to set them manually. > > 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> > You can override any output by creating a custom docbook45.conf with the sections you need to customise, see http://www.methods.co.nz/asciidoc/userguide.html#X7 Cheers Lex > > 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. > -- 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.
