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.5 -r1.1.2.6 --- openacs-4/packages/acs-core-docs/www/docbook-primer.adp 1 Dec 2015 11:17:44 -0000 1.1.2.5 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.adp 1 Dec 2015 14:38:40 -0000 1.1.2.6 @@ -404,7 +404,7 @@ 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 @@ -445,7 +445,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 @@ -486,7 +486,7 @@
The documentation for each package will make up a little "book" -that is structured like this - examples are emphasized: +that is structured like this - examples are emphasized:
book : Docs for one package - templating | @@ -511,11 +511,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
@@ -524,7 +524,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:
@@ -535,7 +535,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
@@ -545,7 +545,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,
@@ -559,15 +559,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>. @@ -590,7 +590,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> @@ -609,7 +609,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>
, @@ -634,7 +634,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"> @@ -733,7 +733,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