Index: openacs-4/packages/acs-core-docs/www/docbook-primer.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.adp,v diff -u -r1.1.2.16 -r1.1.2.17 --- openacs-4/packages/acs-core-docs/www/docbook-primer.adp 11 Jun 2017 08:42:12 -0000 1.1.2.16 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.adp 15 Jun 2017 13:56:41 -0000 1.1.2.17 @@ -410,10 +410,11 @@ tools will be marked up to conform to the DocBook XML DTD. The remaining discussion is about publishing using Docbook.
- is a publishing standard based on XML + is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook:
It is open-source.
A growing community surrounds DocBook (has mailing lists)
A number of free and commercial tools are available for editing and publishing DocBook +
It is open-source.
The DocBook community mailing lists +
A number of free and commercial tools are available for editing and publishing DocBook documents.
It enables us to publish in a variety of formats.
XML separates content from presentation: It relieves each contributor of the burden of presentation, freeing each writer to focus on content and sharing knowledge.
It is well tested technology. It has been in development since @@ -449,7 +450,7 @@ of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically the same elements are valid in the XML DTD as long as -you remember to: +you remember to:
Always close your tags with corresponding end-tags and to not use other tag @@ -471,8 +472,7 @@ that will take an XML document and, given a xsl stylesheet, convert it to HTML. It needs libxml2 and libxslt (available in RPM and DEB formats or from xmlsoft.org.
Some editing tool. A popular one is Emacs with the psgml and -nXML modes. The LDP Author -Guide and DocBook Wiki list some alternates.
The documentation for each package will make up a little "book" that is structured like this - examples are -emphasized: +emphasized:
book : Docs for one package - templating | @@ -516,11 +516,11 @@
- Given that your job starts at the
+ Given that your job starts at the
sect1
-level, all your documents
should open with a <sect1>
-tag
and end with the corresponding </sect1>
.
- You need to feed every <sect1>
two attributes. The first
+ You need to feed every <sect1>
two attributes. The first
attribute, id
, is standard and
can be used with all elements. It comes in very handy when
interlinking between documents (more about this when talking about
@@ -529,7 +529,7 @@
id
has to be unique throughout
the book you're making since the id
's in your sect1
's will turn into filenames when
the book is parsed into HTML.
- The other attribute is xreflabel
. The value of this is the text
+ The other attribute is xreflabel
. The value of this is the text
that will appear as the link when referring to this sect1
.
Right after the opening tag you put the title of the document -
this is usually the same as xreflabel
-attribute. E.g. the top level of
the document you're reading right now looks like this:
@@ -540,7 +540,7 @@ </sect1>
- Inside this container your document will
+ Inside this container your document will
be split up into <sect2>
's,
each with the same requirements - id
and xreflabel
attributes, and a <title>
-tag inside. Actually, the
xreflabel
is never required in
@@ -550,7 +550,7 @@
- For displaying a snippet of code, a
+ For displaying a snippet of code, a
filename or anything else you just want to appear as a part of a
sentence, we use <computeroutput>
and <code>
tags. These
replace the HTML-tag <code>
tag,
@@ -564,15 +564,15 @@
- Linking falls into two different + Linking falls into two different categories: inside the book you're making and outside:
By having unique id
's
you can cross-reference any part of your book with a simple tag,
regardless of where that part is.
-Check out how I link to a subsection of +Check out how I link to a subsection of the Developer's Guide:
Put this in your XML:
- Find information about creating a package in <xref linkend="packages-making-a-package"></xref>. @@ -596,7 +596,7 @@
- If you're hyper-linking out of the
+ If you're hyper-linking out of the
documentation, it works almost the same way as HTML - the tag is
just a little different (<ulink>
):
<ulink url="http://www.oracle.com/">Oracle Corporation</ulink> @@ -615,7 +615,7 @@ Note: The graphics guidelines are not written in stone. Use another valid approach if it works better for you.- To insert a graphic we use the elements + To insert a graphic we use the elements
<mediaobject>
,<imageobject>
,<imagedata>
, @@ -640,7 +640,7 @@
- Here's how you make the DocBook + Here's how you make the DocBook equivalent of the three usual HTML-lists:
- DocBook supports several types of tables,
+ DocBook supports several types of tables,
but in most cases, the <informaltable>
is enough:
<informaltable frame="all"> <tgroup cols="3"> @@ -739,7 +739,7 @@
- Our documentation uses two flavors of
+ Our documentation uses two flavors of
emphasis - italics and bold type. DocBook uses one - <emphasis>
.
The <emphasis>
tag
defaults to italics when parsed. If you're looking for
emphasizing with bold type, use <emphasis