view docs/ReadMe @ 2764:2af3df45f157

Updated main makefile so that when "dw3" and "becker" are activated they call the dependency "dsk".
author drencor-xeen
date Wed, 16 Jan 2013 22:58:36 -0600
parents bc28c3bc3769
children
line wrap: on
line source

Welcome to the OS-9 documentation effort. The motivation behind scanning
and reissuing the documentation is that without documentation no new
users will discover OS-9. This little operating system is more than 20
years old, and we want it to be here for at least another 20 years.

We have therefore tried to find the most durable and rich format
for documents possible. DocBook is more than 10 years old. Older than
MS-Word. It began in 1991 as a joint project of HaL Computer Systems and
O'Reilly. It will very likely be around in 2020 also.  If it isn't it is
a text-based format, so it is possible to reverse-engineer and convert
the format.

Docbook is in a transition from an SGML-based format to XML. The two formats are
not compatible. Primary differences are that the DTD is different. For SGML it is
     <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
and for XML it is
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
Furthermore, some elements are terminated with /, such as <void/>, <colspec/> etc.

DOCBOOK SGML SOFTWARE:
---------------------
To create HTML, PDF or PostScript you must have these RPMs installed on
your RedHat system:

docbook-dtd41-sgml
sgml-common
docbook-utils
docbook-utils-pdf
tetex-dvips
tetex
jadetex
..see also http://sources.redhat.com/docbook-tools/

DocBook Install mini-HOWTO: http://www.tldp.org/HOWTO/mini/DocBook-Install/

Another approach is the xmlto application installed on newer RedHat systems.

DOCBOOK REFERENCES:
-------------------
  The Duck book
    http://www.docbook.org/

  The KDE DocBook Authors guide
    http://i18n.kde.org/doc/markup/

  The Crash Course to Docbook
    http://www.caldera.de/~eric/crash-course/HTML/index.html

  Mark Galassi's tutorial/introduction to writing in DocBook.
    http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html

DOCBOOK EXTENSIONS:
-------------------
At the time of this writing Docbook is undergoing modularisation work.
One of the new modules is the Extended Backhus-Naur Form, which can
be used to describe syntax for shell and the C language. But currently
the renderers don't understand the new elements, so we can't use them.
I've started to rewrite the shell syntax in os9guide/shell.refentry

For Extended Backhus-Naur Forms use:
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook EBNF Module V1.1CR1//EN"
     "http://www.oasis-open.org/docbook/xml/ebnf/1.1CR1/dbebnf.dtd" [


DSSSL STYLESHEET:
----------------
Docbook2pdf uses DSSSL stylesheet. The main one is located in this directory.
Since the default DSSSL stylesheet is updated once in a while and you must
reapply your preferences to the new one, here is what is different from
the default:
- Enumerate chapters and sections
- Use element ids as filenames 
- Don't generate article titlepage on separate page