Re: Using org-mode to create an on-line manual for a software product

[Brett Viren <bv@bnl.gov>]

[-- Attachment #1: Type: text/plain, Size: 1561 bytes --]

ciaran_mulloy <cmulloy@druidsoftware.com> writes:

> I output the manual to latex (nearly 170 pages).
>
> The thought occurs to me that it might be possible to publish it to
> html for use as an on-line manual that could be invoked from within
> the application. Ideally it would be useful to be able to open the
> relevant section in the manual in a browser.

The bulk of this is just typing: C-c C-e h h.  Org's publishing feature
can be applied to layer on more complex exporting rules.

If I were doing this I'd then be faced with these two issues:

 1) forming URLs in the app which correctly point to specific
    headlines/sections in the HTML.

For this I'd be sure to add a unique "<<label>>" after any headlines or
other things I want to reference by URL and then form that URL by ending
it with "#label".

 2) separating the full document into separate, per-section or maybe
    per-subsection HTML files.

In all exporting I've done, a single .org file gives a single .html
file.  If this resulted in an HTML file that was too large to load
quickly, then I'd look at how to split the export up into multiple HTML
files, probably along section lines.  I don't know of a setting that
would do this but one may exist.  I prefer having many, fine-grained
.org files rather than fewer, more monolithic ones so I'd probably
structure the document into individual, comfortably sized .org files.
If I had to then distribute a single PDF from the LaTeX export I might
join the individual section PDFs outside of org (eg, with pdfnup or
something).


-Brett.

[-- Attachment #2: Type: application/pgp-signature, Size: 180 bytes --]