Differences

This shows you the differences between two versions of the page.

--- docbook [2015/06/04 04:47]
slackermedia
+++ docbook [2021/06/03 19:48] (current)
@@ Line 1: / Line 1: @@
-[[{arrowp.png|border:0;background:none;width:0;display:inline-block;position:absolute;top:0;left:0;}digikam|]]
-[[{arrown.png|border:0;background:none;width:0;display:inline-block;position:absolute;top:0;margin-left:2.5em;}jack|]]
 ====== Docbook ======
@@ Line 8: / Line 6: @@
 <WRAP notice prewrap 50%>
 <WRAP rightalign>
 ===== Strengths [Weaknesses] =====
@@ Line 59: / Line 56: @@
 </WRAP>
+===== Install =====
+Docbook is not an application, but a //schema//, meaning that it is nothing more than a set of rules that you follow whilst writing text in any plain text editor of your choice. If you have ever used HTML, it's a little like that; you don't //install// HTML, you just //write// it, and other programmes bear the burden of interpreting it and processing it into a form for public consumption.
+The docbook schema, along with a number of XML tools, comes pre-installed on Slackware.
+To find where you schemas are located, use the ''find'' command:
+<code>
+find / -iname "*docbook*dtd*"
+</code>
+This reveals that the schemas are located in ''/usr/share/xml/docbook/xml-dtd-X.Y'' (where ''X.Y'' is a version number).
+===== Quickstart =====
+The best quickstart guide to Docbook is a short work by David Rugge, Mark Galassi, and Eric Bischoff and located at [[http://xml.web.cern.ch/XML/goossens/dbatcern/dbatcern.html]].
+Here is a basic summary, featuring a severely limited set of functionality:
+==== Docbook Header ====
+The Docbook header is a line of text at the top of a Docbook file which identifies the file as being an XML document following the Docbook schema, and points to where the schema's rules are located on your computer (or a networked location, if you have confidence in your network environment).
+<code>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.5//EN" "/usr/local/share/xml/docbook/4.5/docbookx.dtd">
+</code>
+Docbook can format articles or books; so your header should match what you intend to write:
+  *If writing a book, the header should include: ''DOCTYPE book PUBLIC''
+  *If you are writing an article, then: ''DOCTYPE article PUBLIC''
+<WRAP tip>
+You may never commit the header to memory unless you type it daily, so keep it someplace handy.
+</WRAP>
+The structure of a Docbook file is inflexible. If you are writing an article, then the order of tags is defined by the ''article'' schema, and if you are writing a book then the order of tags is defined by the ''book'' schema. Any deviation from the schema rules will result in invalid XML and usually will be rejected by an XML processor.
+The easiest way to learn what a particular schema demands is straight from the Docbook documentation, available online at [[http://www.docbook.org/tdgXY/en/html/docbook.html]] (where ''tdgXY'' is the version of Docbook that you are using).
+A simple example of a Docbook file using the ''book'' schema:
+<code>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.5//EN" "/usr/local/share/xml/docbook/4.5/docbookx.dtd">
+<book>
+  <title>
+    Texto Ekzempla
+  </title>
+  <chapter>
+    <title>
+      Kiel Libera Programmaro Intigas Arton
+    </title>
+    <para>
+      Elsxuti <ulink url="http://slackware.com">Linukso</ulink>, kaj provu gxin.
+    </para>
+  </chapter>
+</book>
+</code>
+To some degree, it is intuitive as long as you know the tags that you have to work with, and the order of the basic skeleton structure. In the case of a ''book'', the basic structure is:
+  *book
+  *book title
+  *chapter
+  *chapter title
+  *paragraphs
+  *(close chapter tag)
+  *(close book tag)
+This file, saved, is a valid Docbook file, but it is essentially source code.
+==== Processing XML ====
+The easiest XML processor to use is ''xmlto'', an application run in the shell with the sole purpose of translating XML into any number of other formats.
+For example, to convert the book into an html file:
+<code>
+$ mkdir html
+$ xmlto html book.xml -o ./html
+</code>
+Or into plain text:
+<code>
+$ xmlto txt book.xml -o book.txt
+</code>
+There are several ways to generate a PDF, but the most reliable tends to be the Apache Foundation's ''fop'' tool. **Fop** is written in Java, so it does require that the Java runtime is installed.
+==== Apache fop ====
+Install Java (called ''jdk''; the Java Development Kit) from either the ''/extra'' directory on your install media, or from ''http://slackbuilds.org/repository/X.Y/development/jdk/'' (where ''X.Y'' is the version of Slackware that you are running). As Java is currently owned and maintained by Oracle, it requires a EULA agreement that can only be satisfied with a GUI, so you must manually download the Java installer, but you can then run the SlackBuild installer separately so that you have Java properly logged in ''/var/log/packages''.
+Once JDK is installed, install ''fop'' from [[http://slackbuilds.org/repository/14.1/office/fop/?search=fop]].
+To create a PDF, first translate your Docbook file to ''fo'' with ''xmlto'':
+<code>
+$ mkdir ./pdf
+$ xmlto fo book.xml -o ./pdf
+$ fop ./pdf/book.fo -o ./pdf/book.pdf
+</code>
+Wait for the document to process, and at the end you have, in the ''pdf'' directory that you created, a PDF file. Even the hyperlink is fully-functional, just like in a "real" PDF (because it is a real PDF, fully compliant with the spec).
+===== Advanced Techniques =====
+In large works, there is an advantage to keeping your writing modular. Structuring your work such that each chapter is an individual file allows your text editors to load and work on them faster, and makes rearranging the order of the chapters trivial.
+If you choose to work modularly, you only need your Docbook header in the first file, and you should only close your <nowiki><book></nowiki> tag in the final file. For example:
+  *''00.xml'': docbook header + <nowiki><book><title></title></nowiki>
+  *''01.xml'': <nowiki><chapter><title></title><para></para><para>..</para></chapter></nowiki> (and so on)
+  *''02.xml'': <nowiki><chapter><title></title><para></para><para>..</para></chapter></nowiki> (and so on)
+  *''end.xml'': <nowiki></book></nowiki>
+The file ''end.xml'' can literally have nothing but one tag in it: ''</book>'' or, if you have a colophon or appendix, you can place them in your end matter; the point is to wrap the modular files in two extremities (''00.xml'' and ''end.xml'', for example) to ensure that the outermost docbook tags are included once and only once.
+==== Concatenating and Building ====
+Once you have all of your files ready, there is just one additional step to what you already know: you must concatenate all of your files into a temporary master file.
+Assuming you have all of your files in a directory called ''xml'':
+<code>
+$ cd ~/mybook/xml
+$ cat 00.xml 01.xml 03.xml end.xml > tmp.xml
+$ mkdir pdf
+$ xmlto fo tmp.xml ./pdf
+$ fop ./pdf/tmp.fo ./pdf/mybook.pdf
+$ trash tmp.xml
+</code>
+==== Makefiles ====
+The entire build process can be automated with a ''Makefile'', a kind of script for GNU ''make''.
+They have a specific syntax: ''keyword'' -> ''colon'' -> ''required files'' -> ''instruction block''
+This becomes executable by typing ''make keyword''.
+A specific example:
+<code>
+# Makefile by myName
+html: html
+      cat ??.xml end.xml > tmp.xml
+      xmlto html tmp.xml -o ./html
+pdf: pdf
+     cat ??.xml end.xml > tmp.xml
+     xmlto fo tmp.xml -o ./pdf
+</code>
+Each block, somewhat translated:
+<code>
+[keyword]: [what file must exist to proceed]
+[tab] The command to run.
+[tab] Another command to run.
+</code>
+To use it, run ''make'' from the directory where your makefile exists:
+<code>
+$ cd mybook
+$ ls -1
+xml
+Makefile
+$ mkdir html
+$ make html
+</code>
+By scripting with ''make'', the build process is simpler than building manually, and does not require you to remember commands or syntax.
 <WRAP tip>
 **See Also** \\
-sphinx
+[[sphinx|Sphinx]] \\
+[[fountain|Fountain]] \\
+[[screenwriter|Screenwriter-mode]]
+</WRAP>
+<WRAP centeralign>
+<wrap fa>[[digikam|R]]</wrap> <wrap fa>[[start|S]]</wrap> <wrap fa>[[evolvotron|Q]]</wrap>
 </WRAP>
-[[{arrown.png|border:0;background:none;width:0;display:inline-block;float:right;}jack|]][[{arrowp.png|border:0;background:none;width:0;float:right;}digikam|]]