*** /usr/src/gnome-docu/gdp/gdp-handbook.sgml Mon Aug 7 23:48:30 2000
--- gdp-handbook.sgml Tue Sep 19 00:55:15 2000
***************
*** 1155,1181 ****
Introduction to DocBook
To understand DocBook, a basic understanding of SGML is
! helpful. SGML stands for Standard General Markup Language and
! is one of the first markup languages every created. HTML is
! actually derived from SGML and XML is a subset of SGML. SGML
! uses what is called a Document Type Definition to specify
! elements which are contained between
! brackets, < and >. Text is marked by both beginning and
! ending elements, for example in the DocBook DTD, one denotes a
! title with <title>The
! Title</title>.
! The DTD (in the case of the GDP, DocBook) defines rules for how the
! elements can be used. For example, if one element can only be used when
! embedded within another, this is defined in the DTD.
An SGML file is just a plain ASCII file containing the text
with the markup specified above. To convert it to some easily
readable format, you need special tools. The GDP uses DocBook
Tools, a free package of utilities for working with DocBook
! which includes Jade, which does the SGML/DSSL
parsing. You can read more about DocBook Tools in .
--- 1155,1181 ----
Introduction to DocBook
To understand DocBook, a basic understanding of SGML is
! helpful.
! SGML stands for Standard General Markup Language and is one of the
! first markup languages ever created. It uses what are called Document
! Type Definitions to define document structural types such as HTML and
! DocBook. A DTD specifies document elements which
! are delimited by angle brackets, < and >, and document text is then
! marked by both beginning and ending elements. Using the DocBook DTD,
! for example, one marks up a title with
! <title>The Title</title>.
! The DTD (in the case of the GDP, DocBook) also defines rules for how
! the elements can be used. For example, if one element can only be used
! when embedded within another, this is defined in the DTD.
An SGML file is just a plain ASCII file containing the text
with the markup specified above. To convert it to some easily
readable format, you need special tools. The GDP uses DocBook
Tools, a free package of utilities for working with DocBook
! which includes Jade, which does the SGML/DSSSL
parsing. You can read more about DocBook Tools in .
***************
*** 1187,1203 ****
Semantics and Specification Language), which specify the
appearance of various DocBook elements, for example,
what fonts to use for titles and various inline elements, page
! numbering style, and much more. DocBook tools come with a
collection of stylesheets (Norman Walsh's modular
! stylesheets); GNOME Document Project uses some customized
! version of this stylesheets — see .
The advantage of specifying the structure
of a document with SGML instead of specifying the
appearance of the document with a typical
! word processor, or with html, is that the resulting document
can be processed in a variety of ways using the structural
information. Whereas formatting a document for appearance
assumes a medium (typically written text on a standard-sized
--- 1187,1203 ----
Semantics and Specification Language), which specify the
appearance of various DocBook elements, for example,
what fonts to use for titles and various inline elements, page
! numbering style, and much more. DocBook Tools come with a
collection of stylesheets (Norman Walsh's modular
! stylesheets). GNOME Document Project uses a customized
! version of these stylesheets — see .
The advantage of specifying the structure
of a document with SGML instead of specifying the
appearance of the document with a typical
! word processor, or with HTML, is that the resulting document
can be processed in a variety of ways using the structural
information. Whereas formatting a document for appearance
assumes a medium (typically written text on a standard-sized
***************
*** 1206,1224 ****
Braille, audio, and potentially many other formats.
! Using 'content' as the elements to define the text of a document also
! allows for search engines to make use of the actual elements to make a
! "smarter search". For example, if you are searching for all documents
written by the author "Susie" your search engine could be made smart
! enough to only search <author> elements, making for a faster and more
! accurate search.
! Since the overall appearance of the output is determined not by the DTD
! or the SGML document, but rather by a stylesheet, the appearance of a
! document can be easily changed just by changing the stylesheet. This
! allows everyone in the project to create documents that all look the
! same.
As stated before, the GDP uses the DocBook DTD. For a list of
--- 1206,1224 ----
Braille, audio, and potentially many other formats.
! Using elements contained in a document to structure the text of that
! same document also allows search engines to make use of that
! information. For example, if you are searching for all documents
written by the author "Susie" your search engine could be made smart
! enough to only search <author> elements, making for a faster and
! more accurate search.
! Using a stylesheet to determine the overall appearance of the output,
! rather than the DTD or the SGML document, allows everyone in the
! project to create documents with the same look just by using the same
! one. It also allows that look to be updated just by modifying that
! one stylesheet.
As stated before, the GDP uses the DocBook DTD. For a list of
***************
*** 1234,1246 ****
XML and SGML
! In not so distant future (probably before GNOME 2.0),
! DocBook itself and GNOME Documentation project will migrate from
! SGML to XML. This transition should be relatively painless:
(almost) all DocBook tags will remain the same. However, XML has
stricter syntax rules than SGML; thus, some constructions which
are valid in SGML will not be valid in XML. Therefore, to be
! ready for this transistion, it is strongly
advised that the documentation writers conform to XML
syntax rules. Here are most important differences:
--- 1234,1247 ----
XML and SGML
! In the not so distant future (probably before GNOME 2.0),
! DocBook itself and GNOME Documentation Project will migrate from
! SGML to XML, a subset of SGML. This transition should be relatively
! painless:
(almost) all DocBook tags will remain the same. However, XML has
stricter syntax rules than SGML; thus, some constructions which
are valid in SGML will not be valid in XML. Therefore, to be
! ready for this transition, it is strongly
advised that the documentation writers conform to XML
syntax rules. Here are most important differences: