linuxdoc-make 0.13 guide

Gilles Lamiral

Documentation index

You can find the latest release of linuxdoc-make, by Gilles Lamiral, located at:
http://www.linux-france.org/prj/linuxdoc-make/

This document, written in SGML, can be available in several formats: ASCII TeX SGML PostScript HTML HTM PDF Info LyX Man

1. Introduction

The software linuxdoc-make is a bunch of directories, a Makefile, and SGML examples, bundled to create several output formats with just one make command. As a bullet proof, this site part has been generated with linuxdoc-make.

2. Installation

Installation is easy since you just have to unpack the tarball where you want to build your documentation. But to create the documentation you need some tools. They are in section "Prerequisites".

2.1 Prerequisites

You need some freely available softwares: All can be found from freshmeat

• sgmltools 1.0.x (I personally use 1.0.9). Needed
• perl. Needed (by sgmltools 1.0.x at least).
• make (gnu make is nice). Needed
• m4 (gnu m4) because it is a powerful tool. Needed.
• LaTeX (to generate .dvi files). Optional
• ghostview (to view .ps files). Optional
• lynx (lynx is good to render pure ASCII) needed for ASCII format. Optional
• pdflatex. Optional
• tidy (tidy is good at correcting bad HTML) needed for HTML and ASCII format. Optional
• rcs (if you want to use version controls on your documents). Optional
• tar (gnu tar is nice). Optional

You need to know how to write SGML files with the linuxdoc DTD.

2.2 Download

you can download linuxdoc-make via the ftp protocol at http://www.linux-france.org/prj/linuxdoc-make/00_dist/

The archive is named linuxdoc-make-0.13.tgz where 0.13 is the version number.

2.3 Unpacking

You do not have to be root to install linuxdoc-make. You install linuxdoc-make where you want to use it.

gzip -tv linuxdoc-make-0.13.tgz  # optional
cd where/you/want/
tar tzvf linuxdoc-make-0.13.tgz      # see the content
tar xzvf xzvf linuxdoc-make-0.13.tgz # extract
cd linuxdoc-make-0.13
make    # and read because "make" alone is just a reminder
...

You can rename the linuxdoc-make-0.13/ directory like you want at any time. Using make without argument is safe since it gives you the usage (alias make help).

3. Using

3.1 For the impatient

If you write an non-english document (english is the default language), you must end its name with -ll.sgml where ll is the two characters symbolizing your language.

• en: english,english,
• de: deutsch,german,
• nl: nederlands,dutch,
• fr: français,french,
• es: español,spanish,
• da: dansk,danish,
• no: norsk,norwegian,
• se: svenska,swedish,
• pt: portuges,portuguese,
• ca: català,catalan,
• it: italiano,italian,
• ro: românã,romanian

Create a new file with the model.

cd linuxdoc-make-0.13/ # if you're not already there
cp sgml/lidoma-model.en.sgml sgml/myfile.en.sgml

Edit your file sgml/myfile.en.sgml (emacs is good at it). Save your file.

Generate a HTML single page:

make htm

Look at the directory htm/

ls -l htm/
myfile.en.htm

View myfile-en.htm with your favorite web browser (lynx, isn't it?).

Try other output formats:

make
make txt html ps pdf

If you want a clone directory of all the needed files, just type:

make clone

then move the clone/ directory where you want.

3.2 Indexes

Two cases.

First, if there is a file named .index.m4 in any directory, then this file will be processed with m4 to create an index file named index.html.

Second, if there is no file named .index.m4 then an nice ls command will create an index file named index.html in each directory.

      
make indexes
make i       # same thing (I am lazy)
make if      # force mode 

Some treatments use m4. All definitions are from the file include/definitions.m4 and the files it includes. The best way to change any definition is to edit the file named include/override.m4 and modify the values.

Happy doc !