/doc/English/writing-book.html

http://txt2tags.googlecode.com/ · HTML · 455 lines · 439 code · 13 blank · 3 comment · 0 complexity · 1644b2a4b219e0da2d5d9dfc40c1ef21 MD5 · raw file 

    

  1. <?xml version="1.0"
    2. 

  2. ?>
    3. 

  3. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    4. 

  4. <html xmlns="http://www.w3.org/1999/xhtml">
    5. 

  5. <head>
    6. 

  6. <title>Writing Books with Txt2tags</title>
    7. 

  7. <meta name="generator" content="http://txt2tags.org" />
    8. 

  8. 

  9. <!-- Included writing-book.css -->
    10. 

  10. <style type="text/css">
    11. 

  11. body
    12. 

  12. 	{
    13. 

  13. 	font: normal 14pt sans-serif;
    14. 

  14. 	text-align:justify;
    15. 

  15. 	margin: 3em;
    16. 

  16. 	padding: 3em 4em 2em 4em;
    17. 

  17. 	border: 1px solid black;
    18. 

  18. 	}
    19. 

  19. #toc ol
    20. 

  20. 	{
    21. 

  21. 	padding: 2em;
    22. 

  22. 	}
    23. 

  23. #body h1
    24. 

  24. 	{
    25. 

  25. 	border-width: 0px 0px 1px 0px;
    26. 

  26. 	border-style: solid;
    27. 

  27. 	margin-top: 3em;
    28. 

  28. 	}
    29. 

  29. #body p, #body ul, #body ol
    30. 

  30. 	{
    31. 

  31. 	margin-left: 3em;
    32. 

  32. 	}
    33. 

  33. #body li
    34. 

  34. 	{
    35. 

  35. 	/* to make IE happy */
    36. 

  36. 	margin-top: 1em;
    37. 

  37. 	}
    38. 

  38. a
    39. 

  39. 	{
    40. 

  40. 	text-decoration: none;
    41. 

  41. 	}
    42. 

  42. blockquote
    43. 

  43. 	{
    44. 

  44. 	margin-left: 5em;
    45. 

  45. 	margin-top:2em;
    46. 

  46. 	font-style:italic;
    47. 

  47. 	}
    48. 

  48. code
    49. 

  49. 	{
    50. 

  50. 	font-style:italic;
    51. 

  51. 	}
    52. 

  52. hr
    53. 

  53. 	{
    54. 

  54. 	margin-top:3em;
    55. 

  55. 	}
    56. 

  56. </style>
    57. 

  57. 

  58. </head>
    59. 

  59. <body>
    60. 

  60. 

  61. <div class="header" id="header">
    62. 

  62. <h1>Writing Books with Txt2tags</h1>
    63. 

  63. <h3>by Aurelio Jargas</h3>
    64. 

  64. </div>
    65. 

  65. 

  66. <div class="toc" id="toc">
    67. 

  67.   <ol>
    68. 

  68.   <li><a href="#toc1">Preface</a>
    69. 

  69.   </li>
    70. 

  70.   <li><a href="#toc2">Visual Editors VS Markup</a>
    71. 

  71.   </li>
    72. 

  72.   <li><a href="#toc3">The Txt2tags Approach</a>
    73. 

  73.   </li>
    74. 

  74.   <li><a href="#toc4">Fast and Furious</a>
    75. 

  75.   </li>
    76. 

  76.   <li><a href="#toc5">Organize the Sources in Folders</a>
    77. 

  77.   </li>
    78. 

  78.   <li><a href="#toc6">Version Control Made Easy</a>
    79. 

  79.   </li>
    80. 

  80.   <li><a href="#toc7">Quality Matters</a>
    81. 

  81.   </li>
    82. 

  82.   <li><a href="#toc8">Other Advantages</a>
    83. 

  83.   </li>
    84. 

  84.   <li><a href="#toc9">No Tool Fits All Needs</a>
    85. 

  85.   </li>
    86. 

  86.   </ol>
    87. 

  87. 

  88. </div>
    89. 

  89. <div class="body" id="body">
    90. 

  90. 	<blockquote>
    91. 

  91. 	This document is a quick guide showing the benefits of using
    92. 

  92. 	the txt2tags tool on the book writing process. Also applicable
    93. 

  93. 	for other large documents as Guides and Thesis.
    94. 

  94. 	</blockquote>
    95. 

  95. <p></p>
    96. 

  96. <a id="toc1" name="toc1"></a>
    97. 

  97. <h1>1. Preface</h1>
    98. 

  98. <p>
    99. 

  99. I'm the txt2tags<code>[1]</code> author and I wrote two published papers using
    100. 

  100. it: a <a href="http://guia-er.sourceforge.net/">Regular Expressions book</a> (96 pages) and a Shell
    101. 

  101. Programming Course (108 pages). The writing process was smooth and
    102. 

  102. painless, so I want to share this experience.
    103. 

  103. </p>
    104. 

  104. <p>
    105. 

  105. A book is a real big work to get done, but it doesn't have to be a
    106. 

  106. complicated process. To write is to organize ideas into text
    107. 

  107. structures like sections, paragraphs and lists. Txt2tags is a tool
    108. 

  108. that makes this task simple and easy.
    109. 

  109. </p>
    110. 

  110. <p>
    111. 

  111. Writing alone or in a team, with or without version control, technical
    112. 

  112. contents or not, text-only or graphics-enabled. In any case txt2tags
    113. 

  113. can be used as the main tool for the book creation.
    114. 

  114. </p>
    115. 

  115. <p>
    116. 

  116. There is <a href="http://www.picocontainer.org/Contructor+Dependency+Injection+...+Book+Announcement">a book</a> being written right now, using txt2tags.
    117. 

  117. </p>
    118. 

  118. 	<blockquote>
    119. 

  119. 	<code>[1]</code> Txt2tags reads a text file with minimal markup as
    120. 

  120. 	**bold** and //italic// and converts it to documents
    121. 

  121. 	like HTML, LaTeX and Adobe PageMaker. More info:
    122. 

  122. 	<a href="http://txt2tags.org">http://txt2tags.org</a>.
    123. 

  123. 	</blockquote>
    124. 

  124. <p></p>
    125. 

  125. <a id="toc2" name="toc2"></a>
    126. 

  126. <h1>2. Visual Editors VS Markup</h1>
    127. 

  127. <p>
    128. 

  128. The two common ways of writing a book are to use a Visual Editor
    129. 

  129. (<i>Microsoft Word</i>, <i>Adobe Pagemaker</i>) or a Markup Language
    130. 

  130. (<i>LaTeX</i>, <i>docbook</i>).
    131. 

  131. </p>
    132. 

  132. <p>
    133. 

  133. In Visual Editors you write and format the contents at the same time.
    134. 

  134. This approach is nice for small texts, but for a 300 pages book, the
    135. 

  135. formatting consume time and distract the writer.
    136. 

  136. </p>
    137. 

  137. <p>
    138. 

  138. In Markup Languages you write contents and mark it up, so an external
    139. 

  139. program will convert it to the final form. The writer don't mind about
    140. 

  140. formatting, but the process of including <code>&lt;tags&gt;&lt;/tags&gt;</code> and
    141. 

  141. <code>\more{tags}</code> is error prone and very intrusive, making the contents
    142. 

  142. hard to read on the sources.
    143. 

  143. </p>
    144. 

  144. <p>
    145. 

  145. Txt2tags also uses the markup schema, but the big difference is that
    146. 

  146. its marks are very minimal, some indeed are almost natural, as using
    147. 

  147. the hyphen for list items. So the writer can focus on contents only
    148. 

  148. and the source remains readable.
    149. 

  149. </p>
    150. 

  150. <a id="toc3" name="toc3"></a>
    151. 

  151. <h1>3. The Txt2tags Approach</h1>
    152. 

  152. <p>
    153. 

  153. Using txt2tags, the book writing process follow these steps:
    154. 

  154. </p>
    155. 

  155. <ol>
    156. 

  156. <li>The author(s) learn the very simple txt2tags markup rules.
    157. 

  157. <p></p>
    158. 

  158. </li>
    159. 

  159. <li>The author writes the book contents, forgetting about noises
    160. 

  160.   like page margin, font face, colors and sizes.
    161. 

  161. <p></p>
    162. 

  162. </li>
    163. 

  163. <li>The author (or the publisher) open the contents on a graphical text
    164. 

  164.   processor that reads HTML (or LaTeX or ...) and conclude the book
    165. 

  165.   formatting.
    166. 

  166. </li>
    167. 

  167. </ol>
    168. 

  168. 

  169. <p>
    170. 

  170. Step 1 is fast, just a few minutes. Step 2 will take months, and step
    171. 

  171. 3 can take days or weeks.
    172. 

  172. </p>
    173. 

  173. <p>
    174. 

  174. Writing contents is when you will spend more time on the book, so it
    175. 

  175. is really important to make this process a simple, productive and
    176. 

  176. pleasant task.
    177. 

  177. </p>
    178. 

  178. <p>
    179. 

  179. The following are arguments showing that txt2tags can be used to
    180. 

  180. achieve that.
    181. 

  181. </p>
    182. 

  182. <a id="toc4" name="toc4"></a>
    183. 

  183. <h1>4. Fast and Furious</h1>
    184. 

  184. <p>
    185. 

  185. Time is the key. Using txt2tags you will experience a very high
    186. 

  186. productivity period because you write contents, not formatting.
    187. 

  187. </p>
    188. 

  188. <ul>
    189. 

  189. <li><b>Initial Release Fast</b>
    190. 

  190. <p></p>
    191. 

  191.   It is very difficult to start something, but txt2tags has a nice
    192. 

  192.   approach to this problem. Just sit and write plain text. When you're
    193. 

  193.   done, in a few minutes you can add all the txt2tags marks on the
    194. 

  194.   text and the document is ready to be converted and published.
    195. 

  195. <p></p>
    196. 

  196. </li>
    197. 

  197. <li><b>Fast Snapshot Preview</b>
    198. 

  198. <p></p>
    199. 

  199.   No matter which will be the final book format, HTML is the preferred
    200. 

  200.   format to use on the writing time. A snapshot of the current book
    201. 

  201.   state can be done at any time, converting the sources to an HTML
    202. 

  202.   page, so any system with a browser can read it. If you need a
    203. 

  203.   printable version, convert the HTML to PDF with the excellent
    204. 

  204.   <a href="http://www.easysw.com/htmldoc/">htmldoc</a> tool.
    205. 

  205. <p></p>
    206. 

  206. </li>
    207. 

  207. <li><b>Book Contents Overview</b>
    208. 

  208. <p></p>
    209. 

  209.   To quickly have a global overview of the book contents at any time,
    210. 

  210.   just use the txt2tags <i>TOC Only</i> feature. The program shows the
    211. 

  211.   current Table of Contents for the book, with the listing of chapters
    212. 

  212.   and sections, numbered or not, at any depth.
    213. 

  213. <p></p>
    214. 

  214. </li>
    215. 

  215. <li><b>Fast Writing</b>
    216. 

  216. <p></p>
    217. 

  217.   Txt2tags marks are simple and minimalist, very easy to learn. No
    218. 

  218.   names, no options, no parameters. You don't have to stop writing
    219. 

  219.   contents to insert marks, they flow together with the text. If you
    220. 

  220.   don't remember a specific mark at the moment, forget about it and
    221. 

  221.   keep writing. At the end you do a global review on the text and
    222. 

  222.   quickly insert the missing marks.
    223. 

  223. <p></p>
    224. 

  224. </li>
    225. 

  225. <li><b>Fast Conversion</b>
    226. 

  226. <p></p>
    227. 

  227.   Even if you have a 500 pages book, the conversion process will take
    228. 

  228.   just a moment. It is because txt2tags acts as a filter, converting
    229. 

  229.   from one format to another. It does not index, compile, calculate,
    230. 

  230.   compress, draw or do any strong processing on the sources. No more
    231. 

  231.   library, catalog, schema and DTD nightmares.
    232. 

  232. </li>
    233. 

  233. </ul>
    234. 

  234. 

  235. <a id="toc5" name="toc5"></a>
    236. 

  236. <h1>5. Organize the Sources in Folders</h1>
    237. 

  237. <p>
    238. 

  238. Txt2tags has a built in command to include external files in any part
    239. 

  239. of a document, at conversion time. It makes possible to split the
    240. 

  240. sources into several files.
    241. 

  241. </p>
    242. 

  242. <ul>
    243. 

  243. <li><b>Each chapter in a folder</b>
    244. 

  244. <p></p>
    245. 

  245.   You can make a folder for each chapter, storing the sources in a
    246. 

  246.   structured tree. Inside the chapter folder, you can even create
    247. 

  247.   subfolders to store images, configuration and included files.
    248. 

  248. <p></p>
    249. 

  249. </li>
    250. 

  250. <li><b>No file conflicts</b>
    251. 

  251. <p></p>
    252. 

  252.   Separating chapters, different teams can work in different chapters
    253. 

  253.   with no interaction between them. Each team work on its own folder,
    254. 

  254.   avoiding file conflicts due concurrent changes.
    255. 

  255. <p></p>
    256. 

  256. </li>
    257. 

  257. <li><b>Flexible access control</b>
    258. 

  258. <p></p>
    259. 

  259.   Files and folders organized, you can implement access control rules,
    260. 

  260.   setting up properties and permissions for any file or chapter. Do
    261. 

  261.   use the standard system tools to configure the read/write
    262. 

  262.   permissions, like the "users and groups" schema.
    263. 

  263. <p></p>
    264. 

  264. </li>
    265. 

  265. <li><b>Global view of sources</b>
    266. 

  266. <p></p>
    267. 

  267.   Structuring the sources also helps to have a global view of the
    268. 

  268.   book, using any file browser to quickly know the amount of text and
    269. 

  269.   images of any chapter. (Hint: on UNIX, <code>find</code> and <code>du</code> commands)
    270. 

  270. <p></p>
    271. 

  271. </li>
    272. 

  272. <li><b>Work your chapter, forget the others</b>
    273. 

  273. <p></p>
    274. 

  274.   Separating sources into files, you can convert your chapter alone,
    275. 

  275.   not needing to wait for the full book processing. Besides faster
    276. 

  276.   to convert, the chapter alone can be sent to reviewers or be
    277. 

  277.   published alone, as a sample of the full book.
    278. 

  278. <p></p>
    279. 

  279. </li>
    280. 

  280. <li><b>You separate, txt2tags joins</b>
    281. 

  281. <p></p>
    282. 

  282.   When converting, txt2tags will automatically join all the chapters
    283. 

  283.   into the final book, no matter how deep or large is the folder
    284. 

  284.   tree.
    285. 

  285. </li>
    286. 

  286. </ul>
    287. 

  287. 

  288. <a id="toc6" name="toc6"></a>
    289. 

  289. <h1>6. Version Control Made Easy</h1>
    290. 

  290. <p>
    291. 

  291. Txt2tags helps the book version control with line based tools (as
    292. 

  292. <i>CVS</i> and <i>Subversion</i>). The sources are plain text, not compiled
    293. 

  293. data.
    294. 

  294. </p>
    295. 

  295. <ul>
    296. 

  296. <li><b>Work with short lines</b>
    297. 

  297. <p></p>
    298. 

  298.   You can make short lines, breaking them at 72 columns. It will help
    299. 

  299.   on the revision control, because it is line based. If the final
    300. 

  300.   format needs that a paragraph is composed by a single long line (as
    301. 

  301.   PageMaker), txt2tags will join them to you automatically.
    302. 

  302. <p></p>
    303. 

  303. </li>
    304. 

  304. <li><b>Readable sources</b>
    305. 

  305. <p></p>
    306. 

  306.   With very minimal markup, the sources are readable. One can easily
    307. 

  307.   see what has changed from one version to another, the marks don't
    308. 

  308.   hide or pollute the text.
    309. 

  309. <p></p>
    310. 

  310. </li>
    311. 

  311. <li><b>Large contents, small sources</b>
    312. 

  312. <p></p>
    313. 

  313.   As plain text, you can have a huge amount of contents, with a low
    314. 

  314.   disk usage. People can do full checkouts and commits even in slow
    315. 

  315.   connections.
    316. 

  316. <p></p>
    317. 

  317. </li>
    318. 

  318. <li><b>Chapter versioning</b>
    319. 

  319. <p></p>
    320. 

  320.   As seen before, the sources can be organized into folders. This
    321. 

  321.   makes version control separated by chapter, or even sections of
    322. 

  322.   chapters, depending on how granulated you need the versioning.
    323. 

  323. </li>
    324. 

  324. </ul>
    325. 

  325. 

  326. <a id="toc7" name="toc7"></a>
    327. 

  327. <h1>7. Quality Matters</h1>
    328. 

  328. <p>
    329. 

  329. You can write a book. Or you can write THE book. Txt2tags has nice
    330. 

  330. built in features to increase your work quality.
    331. 

  331. </p>
    332. 

  332. <ul>
    333. 

  333. <li><b>Spell Check</b>
    334. 

  334. <p></p>
    335. 

  335.   As all txt2tags marks are symbols and not words, you can use any
    336. 

  336.   spell checker on the sources. It will take care of the text only,
    337. 

  337.   not trying to correct tags.
    338. 

  338. <p></p>
    339. 

  339. </li>
    340. 

  340. <li><b>Alias Database</b>
    341. 

  341. <p></p>
    342. 

  342.   Txt2tags has <i>Pre Processing Filters</i>, where you can define
    343. 

  343.   keyword/value pairs. Wherever the keyword is found on the sources, it
    344. 

  344.   is expanded to the given value at conversion time. For example, you
    345. 

  345.   do use the string <code>URL_GOOGLE</code> on your text and it will appear as
    346. 

  346.   <code>http://www.google.com</code> on the book. If the Google URL changes,
    347. 

  347.   you just change the filter definition and all occurrences of it will
    348. 

  348.   be updated. You can define as many keywords as needed, with no
    349. 

  349.   maximum limit.
    350. 

  350. <p></p>
    351. 

  351. </li>
    352. 

  352. <li><b>Dynamic Content</b>
    353. 

  353. <p></p>
    354. 

  354.   Txt2tags also has a command to include pre-formatted text into the
    355. 

  355.   document when converting it, for example, a software source code
    356. 

  356.   sample. This way you can keep this code sample separated from the
    357. 

  357.   book text and update it by hand or even automatically. A nice idea
    358. 

  358.   is to mark the software source code with special comments, and a
    359. 

  359.   little program extract these marked parts into separate files.
    360. 

  360. <p></p>
    361. 

  361. </li>
    362. 

  362. <li><b>Control Over the Result</b>
    363. 

  363. <p></p>
    364. 

  364.   Txt2tags has <i>Post Processing Filters</i>, where you can define rules
    365. 

  365.   that makes adjustments on the resulting document. So if the standard
    366. 

  366.   txt2tags conversion does not fully satisfy your needs, you can
    367. 

  367.   improve it with your own filters. You can use the power of the
    368. 

  368.   Regular Expressions to match patterns.
    369. 

  369. </li>
    370. 

  370. </ul>
    371. 

  371. 

  372. <a id="toc8" name="toc8"></a>
    373. 

  373. <h1>8. Other Advantages</h1>
    374. 

  374. <p>
    375. 

  375. And there is more!
    376. 

  376. </p>
    377. 

  377. <ul>
    378. 

  378. <li><b>Separate Formatting from Contents</b>
    379. 

  379. <p></p>
    380. 

  380.   Using HTML as the development target format, you can also use CSS
    381. 

  381.   files to experiment different book looks. CSS defines formating for
    382. 

  382.   HTML pages, and there is graphical editors to create CSS files.
    383. 

  383.   A team of designers can work on doing CSS files for the book, while
    384. 

  384.   the writers keep writing.
    385. 

  385. <p></p>
    386. 

  386. </li>
    387. 

  387. <li><b>Include Complicated Structures</b>
    388. 

  388. <p></p>
    389. 

  389.   Txt2tags does have support for all the common structures used in
    390. 

  390.   texts: lists, definitions, quotation, verbatim area and tables. But
    391. 

  391.   if some parts of your book requires a more complicated structure,
    392. 

  392.   you can use the <i>Tagged Include</i> feature, where you insert text
    393. 

  393.   that is already tagged, like a real fancy HTML table. With txt2tags,
    394. 

  394.   exceptions are not a problem!
    395. 

  395. <p></p>
    396. 

  396. </li>
    397. 

  397. <li><b>Do Use Any Editor</b>
    398. 

  398. <p></p>
    399. 

  399.   As plain text source files, even the most modest text editor in the
    400. 

  400.   world can be used to write the book. It doesn't have to have any
    401. 

  401.   feature besides write and save text. If you use the editors with
    402. 

  402.   txt2tags support, you will have <i>Syntax Highlight</i>, which helps to
    403. 

  403.   identify the txt2tags marks. They are: Vim, Emacs, Kate, Nano, gedit
    404. 

  404.   and TextMate.
    405. 

  405. <p></p>
    406. 

  406. </li>
    407. 

  407. <li><b>Technical Support</b>
    408. 

  408. <p></p>
    409. 

  409.   Txt2tags has various channels to get technical support: two mailing
    410. 

  410.   lists (english and portuguese), an IRC channel and even an Orkut
    411. 

  411.   community. And for book projects, your can send direct e-mails to
    412. 

  412.   the program author, who will give priority on the answer.
    413. 

  413. </li>
    414. 

  414. </ul>
    415. 

  415. 

  416. <a id="toc9" name="toc9"></a>
    417. 

  417. <h1>9. No Tool Fits All Needs</h1>
    418. 

  418. <p>
    419. 

  419. There are some special cases where txt2tags is not a good tool for
    420. 

  420. writing books.
    421. 

  421. </p>
    422. 

  422. <ul>
    423. 

  423. <li><b>Very Complex Books</b>
    424. 

  424. <p></p>
    425. 

  425.   Books that uses lots of complicated tables, formulas or specific
    426. 

  426.   structures, needs a graphical editor or a more complex markup
    427. 

  427.   language, as LaTeX. If your book matches this description, txt2tags cannot help you.
    428. 

  428. <p></p>
    429. 

  429. </li>
    430. 

  430. <li><b>Footnotes</b>
    431. 

  431. <p></p>
    432. 

  432.   Txt2tags does not have footnotes support. If you will use just a
    433. 

  433.   few, you can add them later. But if you plan to make an intense
    434. 

  434.   footnotes use, txt2tags cannot help you.
    435. 

  435. <p></p>
    436. 

  436. </li>
    437. 

  437. <li><b>References for Pages, Tables and Images</b>
    438. 

  438. <p></p>
    439. 

  439.   One can use a graphical editor at the publishing time to include
    440. 

  440.   indexes for pages, tables and images, no problem at all. But if you
    441. 

  441.   plan to refer to them inside the text like
    442. 

  442.   "<i>See table 4.11 on page 35</i>", txt2tags cannot help you.
    443. 

  443. </li>
    444. 

  444. </ul>
    445. 

  445. 

  446. <hr class="light" />
    447. 

  447. <p>
    448. 

  448. <i>Writing Books with Txt2tags - Oct/2004</i>
    449. 

  449. (<a href="writing-book.t2t">see source</a>)
    450. 

  450. </p>
    451. 

  451. </div>
    452. 

  452. 

  453. <!-- xhtml code generated by txt2tags 2.6b (http://txt2tags.org) -->
    454. 

  454. <!-- cmdline: txt2tags writing-book.t2t -->
    455. 

  455. </body></html>
    456.