Differences

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

--- docbook [2015/06/05 22:21]
slackermedia
+++ docbook [2015/07/09 19:32]
slackermedia
@@ 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;}ffmpeg|]]
+[[{arrown.png|border:0;background:none;width:0;display:inline-block;position:absolute;top:0;margin-left:2.5em;}evolvotron|]]
 ====== Docbook ======
@@ Line 62: / Line 62: @@
 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. The schemas are located in ''/usr/share/xml/docbook/xml-dtd-X.Y'' (where ''X.Y'' is a version number).
+The docbook schema, along with a number of XML tools, comes pre-installed on Slackware.
-===== Quickstart =====
+To find where you schemas are located, use the ''find'' command:
-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]].
+<code>
+find / -iname "*docbook*dtd*"
+</code>
-The basics
+This reveals that the schemas are located in ''/usr/share/xml/docbook/xml-dtd-X.Y'' (where ''X.Y'' is a version number).
---> Adding the Docbook Header <--
-One thing text2docbook did not add for you (because we commented it out)
+===== Quickstart =====
-is the docbook header.  This is the function of the config.sh I have
-with my sources; it permits the user to enter their docbook path
-(DOCLOC) and the creates a simple docbook.header file with the docbook
-header in it along with the appropriate path to the docbookx.dtd file.
-If you are literally going to be working on just one system such that
+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]].
-the location of docbookx.dtd will never change, you could hardcode
-this into the first xml file, or you can keep it modular and create a
-docbook.header file.  Point is, this declaration needs to happen at
-the very beginning of your work:
-  p--------------------------------------------------------------q
+Here is a basic summary, featuring a severely limited set of functionality:
-  |  <!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.4//EN"  |
-  |  "/usr/local/share/xml/docbook/4.4/docbookx.dtd">            |
-  |                                                              |
-  b------------------------------------/fig 5. the docbook header!
-Docbook can format articles or books; so if you're writing a book the
+==== Docbook Header ====
-header should have: DOCTYPE book PUBLIC
-If you are writing an article, then you want:
+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).
-DOCTYPE article PUBLIC
-And, as I've said already, the actual PATH to docbookx.dtd is
+<code>
-something you'll need to define for the system.  You can always find
+<?xml version='1.0' encoding='utf-8' ?>
-that out with this command:
+<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.5//EN" "/usr/local/share/xml/docbook/4.5/docbookx.dtd">
+</code>
-  p-------------------------------------------------q
+Docbook can format articles or books; so your header should match what you intend to write:
-  |  bash$ find /usr/share/xml/ -iname docbook*dtd  |
-  |                                                 |
-  b-------------------------------------/fig 6. find!
---> xmlto html and xmlto pdf <--
+  *If writing a book, the header should include: ''DOCTYPE book PUBLIC''
+  *If you are writing an article, then: ''DOCTYPE article PUBLIC''
-Now we're ready to take all that confusing xml and make it into HTML
+<WRAP tip>
-so we can look at it in a web browser and a pdf so we can send it to
+You may never commit the header to memory unless you type it daily, so keep it someplace handy.
-all of our friends and carry it around on our mobiles and tablets.
+</WRAP>
-The application we use first is xmlto.
-First, get all the xml files into one big document:
-  p-----------------------------------------------------q
-  |  bash$ cat docbook.header *.docbook.xml > tmp.xml   |
-  |                                                     |
-  b------------------------------/fig 7. creating tmp.xml
-And now to create a directory for the htmls files, and process tmp.xml
-with xmlto:
-  p---------------------------------------------q
-  |  bash$ mkdir ./html                         |
-  |  bash$ xmlto html tmp.xml -o ./html         |
-  |                                             |
-  b----------------------/fig 8. xmlto in action!
-Obviously the syntax of xmlto is...
-xmlto - the command
-html - the type of output we want
--o - the flag to tell xmlto where to dump the output files
-And now if you navigate into the html folder you'll find a BUNCH of
-html files, and if you launch konqueror or some other web browser to
-that folder, then you'll see it lookin' all pretty and really nicely
-laid out and stuff.
-For a pdf, the first and second steps are essentially the same; if you
-already have a concatenated tmp.xml then you can skip that step, and
-the second is similar:
-  p---------------------------------------------q
+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.
-  |  bash$ mkdir ./pdf                          |
-  |  bash$ xmlto fo tmp.xml -o ./pdf            |
-  |                                             |
-  b----------------/fig 9. xmlto in action again!
-WTF is an fo file?  I don't know, but it's the intermediate step
+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).
-between raw unadulterated XML and a fancy hot-link-clickable PDF.  It
-dumps out a tmp.fo in your ./pdf directory.
-To get the tmp.fo into pdf, we use Apache's fop:
+A simple example of a Docbook file using the ''book'' schema:
-  p-----------------------------------------------------q
+<code>
-  |  bash$ fop ./pdf/tmp.fo ./pdf/myBook_by_myName.pdf  |
+<?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">
-  b-----------------------------------------/fig 10. fop!
-And now in your ./pdf directory you have a really really cool pdf with
+<book>
-a table of contents that is clickable, and text that can be copied and
+  <title>
-pasted, and all that good stuff, just like the pro's.  Except, in our
+    Texto Ekzempla
-case, we didn't have to sell our souls to the evil that is Ad0be :^)
+  </title>
-So, that's it, you're done.  Oh, well, unless you want to take it to
+  <chapter>
-the next level.  I mean, if you think you can handle it.  Well, take a
+    <title>
-moment, think it over, and if you want this to be a really
+      Kiel Libera Programmaro Intigas Arton
-lean-and-mean docbook-wielding machine, gather your party and venture
+    </title>
-forth:
+    <para>
+      Elsxuti <ulink url="http://slackware.com">Linukso</ulink>, kaj provu gxin.
+    </para>
+  </chapter>
+</book>
---> The Makefile <--
+</code>
-This section is going to assume that you have compiled code from
+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:
-source before.  If you have never done this, you should go learn how
-to do that and then return to this section.  I think I have an episode
-of my podcast the "GNU World Order" on the subject.  So, do what you
-have to do; learn it, install GCC or bin-utils or whatever it's called
-on your distro.  If you're using Slackware or freeBSD, you already
-have that stuff installed.
-So, Makefiles are basically litle scripts for GNU Make.  They have a
+  *book
-specific syntax, and are infinitely flexible, but we're gonig to keep
+  *book title
-it simple here because, well, that's all we need, plus I'm a Makefile
+  *chapter
-noob.
+  *chapter title
+  *paragraphs
+  *(close chapter tag)
+  *(close book tag)
-The Makefile syntax is:
+This file, saved, is a valid Docbook file, but it is essentially source code.
-some term -> colon -> instruction set
-...which then becomes executable by tying make (term).
+==== Processing XML ====
-So create a text file in your editor and call it Makefile
+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.
-(capitalization counts) and try this:
-  p------------------------------------------------------------q
+For example, to convert the book into an html file:
-  | # Makefile by myName                                       |
-  |                                                            |
-  | html: docbook.header *.docbook.xml                         |
-  |       cat docbook.header *.docbook.xml credits > tmp.xml   |
-  |       xmlto html tmp.xml -o ./html                         |
-  |                                                            |
-  b----------------------------/fig. 11. your very own Makefile!
-So the line that starts with html is the target line, meaning that
+<code>
-when you type make html, GNU Make looks at those files; if they are
+$ mkdir html
-not present, it returns 1 (that is, it gets borked).  Assuming
+$ xmlto html book.xml -o ./html
-everything's good, GNU Make continues and processes the next line,
+</code>
-which is the cat line that generates tmp.xml, and then the xmlto
-command.
-Try it:
-  p-----------------------q
+Or into plain text:
-  |  bash$ make html      |
-  |                       |
-  b---------------/fig. 12!
-And watch in amazement as your html files are generated with that one
+<code>
-simple step.  This is helpful largely because in real life you'll be
+$ xmlto txt book.xml -o book.txt
-making your html files a lot, as you find little layout errors here,
+</code>
-or you update your book there, and so on.
-You can do the same for your pdf generations:
+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.
-  p-------------------------------------------------------------q
+==== Apache fop ====
-  | # pretend like the rest of the Makefile is right here       |
-  |                                                             |
-  | pdf: docbook.header *.docbook.xml                           |
-  |      cat docbook.header *.docbook.xml > tmp.xml             |
-  |      xmlto fo tmp.xml -o ./pdf                              |
-  |      fop ./pdf/tmp.fo ./pdf/docbook.pdf                     |
-  |                                                             |
-  b-------------------------------/fig. 13. More of the Makefile!
-Same deal.
+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''.
-So, since it is kind of probable that you'll be running make a lot,
+Once JDK is installed, install ''fop'' from [[http://slackbuilds.org/repository/14.1/office/fop/?search=fop]].
-the chances of you generating lots of little tmp.xml files and html
-files and stuff like that is great.  It's quite helpful, and a feature
-of GNU Make, to be able to clean all that cruft out.  This way you can
-always get back to your base state and feel confident that your make
-isn't failing because of some old file lying around.
-This is usually done with "make clean" but I also like to implement a
+To create a PDF, first translate your Docbook file to ''fo'' with ''xmlto'':
-"make tidy", where "tidy" will remove the little intermediary files
-like the tmp.fo and tmp.xml, and "clean" removes those PLUS the big
-main files like the html and pdf files and my custom .header file.  I
-don't know that there is a canonical way to do this but here's what I
-do:
-  p-------------------------------------------------------------q
+<code>
-  | # pretend like the rest of the Makefile is right here       |
+$ mkdir ./pdf
-  |                                                             |
+$ xmlto fo book.xml -o ./pdf
-  | tidy:                                                       |
+$ fop ./pdf/book.fo -o ./pdf/book.pdf
-  |      -rm -f ./pdf/*.fo tmp.xml *.out                        |
+</code>
-  |                                                             |
-  | clean:                                                      |
-  |      -rm -f ./pdf/*.fo ./pdf/.pdf tmp.xml *.out             |
-  |      -rm -f *.header                                        |
-  |      -rm -f html/*.html                                     |
-  |                                                             |
-  b----------------------------------/fig. 14 Makefile additions!
+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).
---> Closing Thoughts <--
+===== Advanced Techniques =====
-A bird in hand is better than two in the bush.
+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.
-A penny saved is a penny earned.
+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:
-An apple a day keeps the doctor away.
+  *''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>
-Meat is murder.
+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.
-Kill your TV.
+==== Concatenating and Building ====
-I'd rather be naked than wear fur.
+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.
-Save the Earth: Hang a CEO.
+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''.
-Credits
+They have a specific syntax: ''keyword'' -> ''colon'' -> ''required files'' -> ''instruction block''
-     http://klaatu.hackerpublicradio.org
+This becomes executable by typing ''make keyword''.
-     my little oggcast about GNU Linux
-     the first "podcast" to release only in ogg
-     http://www.hackerpublicradio.org
+A specific example:
-     a daily podcast for hackers, by hackers
-     http://www.kernelpanicoggcast.net
+<code>
-     a bunch of guys talking about GNU Linux
+# Makefile by myName
-     http://www.linuxcranks.info
+html: html
-     geeks talking about...GNU Linux
+      cat ??.xml end.xml > tmp.xml
+      xmlto html tmp.xml -o ./html
-     http://www.slackermedia.info
+pdf: pdf
-     a DIY turn slackware into a multimedia distro
+     cat ??.xml end.xml > tmp.xml
+     xmlto fo tmp.xml -o ./pdf
+</code>
-     http://www.slackware.com
+Each block, somewhat translated:
-     get slack
-     http://www.slackbuilds.org
+<code>
-     get slackbuilds
+[keyword]: [what file must exist to proceed]
+[tab] The command to run.
+[tab] Another command to run.
+</code>
-     http://www.sbopkg.org
+To use it, run ''make'' from the directory where your makefile exists:
-     slackbuilds.org front end
-http://www.docbook.org/tdg51/en/html/docbook.html
+<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|Fountain]] \\
-screenwriter
+[[screenwriter|Screenwriter-mode]]
 </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|]]
+[[{arrown.png|border:0;background:none;width:0;display:inline-block;float:right;}digikam|]][[{arrowp.png|border:0;background:none;width:0;float:right;}evolvotron|]]