Differences

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

--- docbook [2015/06/05 23:00]
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;}ffmpeg|]]
 ====== Docbook ======
@@ Line 109: / Line 107: @@
 <book>
   <title>
-    Restricting Less
+    Texto Ekzempla
   </title>
-  <chapter id="one">
+  <chapter>
-    <title>How Open Source Excludes No One</title>
+    <title>
+      Kiel Libera Programmaro Intigas Arton
+    </title>
     <para>
-      Download it and try it
+      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.
-And now to create a directory for the files, and process tmp.xml
+==== Processing XML ====
-with xmlto:
-  p---------------------------------------------q
+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.
-  |  bash$ mkdir ./html                         |
-  |  bash$ xmlto html tmp.xml -o ./html         |
-  |                                             |
-  b----------------------/fig 8. xmlto in action!
-Obviously the syntax of xmlto is...
+For example, to convert the book into an html file:
-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
+<code>
-html files, and if you launch konqueror or some other web browser to
+$ mkdir html
-that folder, then you'll see it lookin' all pretty and really nicely
+$ xmlto html book.xml -o ./html
-laid out and stuff.
+</code>
-For a pdf, the first and second steps are essentially the same; if you
+Or into plain text:
-already have a concatenated tmp.xml then you can skip that step, and
-the second is similar:
-  p---------------------------------------------q
+<code>
-  |  bash$ mkdir ./pdf                          |
+$ xmlto txt book.xml -o book.txt
-  |  bash$ xmlto fo tmp.xml -o ./pdf            |
+</code>
-  |                                             |
-  b----------------/fig 9. xmlto in action again!
-WTF is an fo file?  I don't know, but it's the intermediate step
+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.
-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:
+==== Apache fop ====
-  p-----------------------------------------------------q
+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''.
-  |  bash$ fop ./pdf/tmp.fo ./pdf/myBook_by_myName.pdf  |
-  |                                                     |
-  b-----------------------------------------/fig 10. fop!
-And now in your ./pdf directory you have a really really cool pdf with
+Once JDK is installed, install ''fop'' from [[http://slackbuilds.org/repository/14.1/office/fop/?search=fop]].
-a table of contents that is clickable, and text that can be copied and
-pasted, and all that good stuff, just like the pro's.  Except, in our
-case, we didn't have to sell our souls to the evil that is Ad0be :^)
-So, that's it, you're done.  Oh, well, unless you want to take it to
+To create a PDF, first translate your Docbook file to ''fo'' with ''xmlto'':
-the next level.  I mean, if you think you can handle it.  Well, take a
-moment, think it over, and if you want this to be a really
-lean-and-mean docbook-wielding machine, gather your party and venture
-forth:
+<code>
+$ mkdir ./pdf
+$ xmlto fo book.xml -o ./pdf
+$ fop ./pdf/book.fo -o ./pdf/book.pdf
+</code>
---> The Makefile <--
+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).
-This section is going to assume that you have compiled code from
+===== Advanced Techniques =====
-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
+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.
-specific syntax, and are infinitely flexible, but we're gonig to keep
-it simple here because, well, that's all we need, plus I'm a Makefile
-noob.
-The Makefile syntax is:
+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:
-some term -> colon -> instruction set
-...which then becomes executable by tying make (term).
+  *''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>
-So create a text file in your editor and call it Makefile
+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.
-(capitalization counts) and try this:
-  p------------------------------------------------------------q
+==== Concatenating and Building ====
-  | # 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
+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.
-when you type make html, GNU Make looks at those files; if they are
-not present, it returns 1 (that is, it gets borked).  Assuming
-everything's good, GNU Make continues and processes the next line,
-which is the cat line that generates tmp.xml, and then the xmlto
-command.
-Try it:
-  p-----------------------q
+Assuming you have all of your files in a directory called ''xml'':
-  |  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
+$ cd ~/mybook/xml
-making your html files a lot, as you find little layout errors here,
+$ cat 00.xml 01.xml 03.xml end.xml > tmp.xml
-or you update your book there, and so on.
+$ mkdir pdf
+$ xmlto fo tmp.xml ./pdf
+$ fop ./pdf/tmp.fo ./pdf/mybook.pdf
+$ trash tmp.xml
+</code>
-You can do the same for your pdf generations:
+==== Makefiles ====
-  p-------------------------------------------------------------q
+The entire build process can be automated with a ''Makefile'', a kind of script for GNU ''make''.
-  | # 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.
+They have a specific syntax: ''keyword'' -> ''colon'' -> ''required files'' -> ''instruction block''
-So, since it is kind of probable that you'll be running make a lot,
+This becomes executable by typing ''make keyword''.
-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
+A specific example:
-"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       |
+# Makefile by myName
-  |                                                             |
-  | tidy:                                                       |
-  |      -rm -f ./pdf/*.fo tmp.xml *.out                        |
-  |                                                             |
-  | clean:                                                      |
-  |      -rm -f ./pdf/*.fo ./pdf/.pdf tmp.xml *.out             |
-  |      -rm -f *.header                                        |
-  |      -rm -f html/*.html                                     |
-  |                                                             |
-  b----------------------------------/fig. 14 Makefile additions!
+html: html
+      cat ??.xml end.xml > tmp.xml
+      xmlto html tmp.xml -o ./html
---> Closing Thoughts <--
+pdf: pdf
+     cat ??.xml end.xml > tmp.xml
+     xmlto fo tmp.xml -o ./pdf
+</code>
-A bird in hand is better than two in the bush.
+Each block, somewhat translated:
-A penny saved is a penny earned.
+<code>
+[keyword]: [what file must exist to proceed]
-An apple a day keeps the doctor away.
+[tab] The command to run.
+[tab] Another command to run.
-Meat is murder.
+</code>
-Kill your TV.
-I'd rather be naked than wear fur.
-Save the Earth: Hang a CEO.
-Credits
-     http://klaatu.hackerpublicradio.org
-     my little oggcast about GNU Linux
-     the first "podcast" to release only in ogg
-     http://www.hackerpublicradio.org
-     a daily podcast for hackers, by hackers
-     http://www.kernelpanicoggcast.net
-     a bunch of guys talking about GNU Linux
-     http://www.linuxcranks.info
-     geeks talking about...GNU Linux
-     http://www.slackermedia.info
-     a DIY turn slackware into a multimedia distro
-     http://www.slackware.com
-     get slack
-     http://www.slackbuilds.org
-     get slackbuilds
-     http://www.sbopkg.org
-     slackbuilds.org front end
+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|Fountain]] \\
-screenwriter
+[[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|]]