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

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

[ciaran_mulloy]

Hi!
I've been using Org-mode for creating an administration manual and user 
guide for a software product in the company I work.

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.

Does anyone have practical experience, or suggestions of implementing 
such a solution with org-mode? The software application runs in a CentOS 
6.X environment

Regards,
Ciaran Mulloy

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

[Melanie Bacou]

Ciaran
Have a look at ox-twbs in MELPA https://github.com/marsmining/ox-twbs. 
This will publish your org files to HTML with Twitter Bootstrap CSS 
support that you can customize.
There's also https://github.com/fniessen/org-html-themes
--Mel.

On 2/24/2015 9:55 AM, ciaran_mulloy wrote:
> Hi!
> I've been using Org-mode for creating an administration manual and user
> guide for a software product in the company I work.
>
> 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.
>
> Does anyone have practical experience, or suggestions of implementing
> such a solution with org-mode? The software application runs in a CentOS
> 6.X environment
>
> Regards,
> Ciaran Mulloy
>
>
>

-- 
Melanie BACOU
International Food Policy Research Institute
Snr. Program Manager, HarvestChoice
E-mail m.bacou@cgiar.org
Visit www.harvestchoice.org

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

[Melanie Bacou]

Another hosted service that uses markdown (not org-mode) 
http://readthedocs.org/


On 2/24/2015 8:38 PM, Melanie Bacou wrote:
> Ciaran
> Have a look at ox-twbs in MELPA https://github.com/marsmining/ox-twbs.
> This will publish your org files to HTML with Twitter Bootstrap CSS
> support that you can customize.
> There's also https://github.com/fniessen/org-html-themes
> --Mel.
>
> On 2/24/2015 9:55 AM, ciaran_mulloy wrote:
>> Hi!
>> I've been using Org-mode for creating an administration manual and user
>> guide for a software product in the company I work.
>>
>> 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.
>>
>> Does anyone have practical experience, or suggestions of implementing
>> such a solution with org-mode? The software application runs in a CentOS
>> 6.X environment
>>
>> Regards,
>> Ciaran Mulloy
>>
>>
>>
>

-- 
Melanie BACOU
International Food Policy Research Institute
Snr. Program Manager, HarvestChoice
E-mail m.bacou@cgiar.org
Visit www.harvestchoice.org

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

[Brett Viren]

[-- 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 --]

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

[Rasmus]

Brett Viren <bv@bnl.gov> writes:

> 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".

For sections *I'd* use a custom-id property...

>  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).

Have you checked the INCLUDE keyword?

—Rasmus

-- 
This is the kind of tedious nonsense up with which I will not put