Differences

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

--- docbook [2015/06/06 00:18]
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 172: / Line 170: @@
 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 ====
+===== 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.
+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:
---> The Makefile <--
+  *''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>
-This section is going to assume that you have compiled code from
+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.
-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
+==== Concatenating and Building ====
-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:
+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.
-some term -> colon -> instruction set
-...which then becomes executable by tying make (term).
+Assuming you have all of your files in a directory called ''xml'':
-So create a text file in your editor and call it Makefile
+<code>
-(capitalization counts) and try this:
+$ 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>
-  p------------------------------------------------------------q
+==== Makefiles ====
-  | # 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
+The entire build process can be automated with a ''Makefile'', a kind of script for GNU ''make''.
-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
+They have a specific syntax: ''keyword'' -> ''colon'' -> ''required files'' -> ''instruction block''
-  |  bash$ make html      |
-  |                       |
-  b---------------/fig. 12!
-And watch in amazement as your html files are generated with that one
+This becomes executable by typing ''make keyword''.
-simple step.  This is helpful largely because in real life you'll be
-making your html files a lot, as you find little layout errors here,
-or you update your book there, and so on.
-You can do the same for your pdf generations:
+A specific example:
-  p-------------------------------------------------------------q
+<code>
-  | # pretend like the rest of the Makefile is right here       |
+# Makefile by myName
-  |                                                             |
-  | 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.
+html: html
+      cat ??.xml end.xml > tmp.xml
+      xmlto html tmp.xml -o ./html
-So, since it is kind of probable that you'll be running make a lot,
+pdf: pdf
-the chances of you generating lots of little tmp.xml files and html
+     cat ??.xml end.xml > tmp.xml
-files and stuff like that is great.  It's quite helpful, and a feature
+     xmlto fo tmp.xml -o ./pdf
-of GNU Make, to be able to clean all that cruft out.  This way you can
+</code>
-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
+Each block, somewhat translated:
-"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       |
+[keyword]: [what file must exist to proceed]
-  |                                                             |
+[tab] The command to run.
-  | tidy:                                                       |
+[tab] Another command to run.
-  |      -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!
---> Closing Thoughts <--
-A bird in hand is better than two in the bush.
-A penny saved is a penny earned.
-An apple a day keeps the doctor away.
-Meat is murder.
-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|]]