PageRenderTime 42ms CodeModel.GetById 22ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 0ms

/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?>
  3<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  4<html xmlns="http://www.w3.org/1999/xhtml">
  5<head>
  6<title>Writing Books with Txt2tags</title>
  7<meta name="generator" content="http://txt2tags.org" />
  8
  9<!-- Included writing-book.css -->
 10<style type="text/css">
 11body
 12	{
 13	font: normal 14pt sans-serif;
 14	text-align:justify;
 15	margin: 3em;
 16	padding: 3em 4em 2em 4em;
 17	border: 1px solid black;
 18	}
 19#toc ol
 20	{
 21	padding: 2em;
 22	}
 23#body h1
 24	{
 25	border-width: 0px 0px 1px 0px;
 26	border-style: solid;
 27	margin-top: 3em;
 28	}
 29#body p, #body ul, #body ol
 30	{
 31	margin-left: 3em;
 32	}
 33#body li
 34	{
 35	/* to make IE happy */
 36	margin-top: 1em;
 37	}
 38a
 39	{
 40	text-decoration: none;
 41	}
 42blockquote
 43	{
 44	margin-left: 5em;
 45	margin-top:2em;
 46	font-style:italic;
 47	}
 48code
 49	{
 50	font-style:italic;
 51	}
 52hr
 53	{
 54	margin-top:3em;
 55	}
 56</style>
 57
 58</head>
 59<body>
 60
 61<div class="header" id="header">
 62<h1>Writing Books with Txt2tags</h1>
 63<h3>by Aurelio Jargas</h3>
 64</div>
 65
 66<div class="toc" id="toc">
 67  <ol>
 68  <li><a href="#toc1">Preface</a>
 69  </li>
 70  <li><a href="#toc2">Visual Editors VS Markup</a>
 71  </li>
 72  <li><a href="#toc3">The Txt2tags Approach</a>
 73  </li>
 74  <li><a href="#toc4">Fast and Furious</a>
 75  </li>
 76  <li><a href="#toc5">Organize the Sources in Folders</a>
 77  </li>
 78  <li><a href="#toc6">Version Control Made Easy</a>
 79  </li>
 80  <li><a href="#toc7">Quality Matters</a>
 81  </li>
 82  <li><a href="#toc8">Other Advantages</a>
 83  </li>
 84  <li><a href="#toc9">No Tool Fits All Needs</a>
 85  </li>
 86  </ol>
 87
 88</div>
 89<div class="body" id="body">
 90	<blockquote>
 91	This document is a quick guide showing the benefits of using
 92	the txt2tags tool on the book writing process. Also applicable
 93	for other large documents as Guides and Thesis.
 94	</blockquote>
 95<p></p>
 96<a id="toc1" name="toc1"></a>
 97<h1>1. Preface</h1>
 98<p>
 99I'm the txt2tags<code>[1]</code> author and I wrote two published papers using
100it: a <a href="http://guia-er.sourceforge.net/">Regular Expressions book</a> (96 pages) and a Shell
101Programming Course (108 pages). The writing process was smooth and
102painless, so I want to share this experience.
103</p>
104<p>
105A book is a real big work to get done, but it doesn't have to be a
106complicated process. To write is to organize ideas into text
107structures like sections, paragraphs and lists. Txt2tags is a tool
108that makes this task simple and easy.
109</p>
110<p>
111Writing alone or in a team, with or without version control, technical
112contents or not, text-only or graphics-enabled. In any case txt2tags
113can be used as the main tool for the book creation.
114</p>
115<p>
116There is <a href="http://www.picocontainer.org/Contructor+Dependency+Injection+...+Book+Announcement">a book</a> being written right now, using txt2tags.
117</p>
118	<blockquote>
119	<code>[1]</code> Txt2tags reads a text file with minimal markup as
120	**bold** and //italic// and converts it to documents
121	like HTML, LaTeX and Adobe PageMaker. More info:
122	<a href="http://txt2tags.org">http://txt2tags.org</a>.
123	</blockquote>
124<p></p>
125<a id="toc2" name="toc2"></a>
126<h1>2. Visual Editors VS Markup</h1>
127<p>
128The two common ways of writing a book are to use a Visual Editor
129(<i>Microsoft Word</i>, <i>Adobe Pagemaker</i>) or a Markup Language
130(<i>LaTeX</i>, <i>docbook</i>).
131</p>
132<p>
133In Visual Editors you write and format the contents at the same time.
134This approach is nice for small texts, but for a 300 pages book, the
135formatting consume time and distract the writer.
136</p>
137<p>
138In Markup Languages you write contents and mark it up, so an external
139program will convert it to the final form. The writer don't mind about
140formatting, but the process of including <code>&lt;tags&gt;&lt;/tags&gt;</code> and
141<code>\more{tags}</code> is error prone and very intrusive, making the contents
142hard to read on the sources.
143</p>
144<p>
145Txt2tags also uses the markup schema, but the big difference is that
146its marks are very minimal, some indeed are almost natural, as using
147the hyphen for list items. So the writer can focus on contents only
148and the source remains readable.
149</p>
150<a id="toc3" name="toc3"></a>
151<h1>3. The Txt2tags Approach</h1>
152<p>
153Using txt2tags, the book writing process follow these steps:
154</p>
155<ol>
156<li>The author(s) learn the very simple txt2tags markup rules.
157<p></p>
158</li>
159<li>The author writes the book contents, forgetting about noises
160  like page margin, font face, colors and sizes.
161<p></p>
162</li>
163<li>The author (or the publisher) open the contents on a graphical text
164  processor that reads HTML (or LaTeX or ...) and conclude the book
165  formatting.
166</li>
167</ol>
168
169<p>
170Step 1 is fast, just a few minutes. Step 2 will take months, and step
1713 can take days or weeks.
172</p>
173<p>
174Writing contents is when you will spend more time on the book, so it
175is really important to make this process a simple, productive and
176pleasant task.
177</p>
178<p>
179The following are arguments showing that txt2tags can be used to
180achieve that.
181</p>
182<a id="toc4" name="toc4"></a>
183<h1>4. Fast and Furious</h1>
184<p>
185Time is the key. Using txt2tags you will experience a very high
186productivity period because you write contents, not formatting.
187</p>
188<ul>
189<li><b>Initial Release Fast</b>
190<p></p>
191  It is very difficult to start something, but txt2tags has a nice
192  approach to this problem. Just sit and write plain text. When you're
193  done, in a few minutes you can add all the txt2tags marks on the
194  text and the document is ready to be converted and published.
195<p></p>
196</li>
197<li><b>Fast Snapshot Preview</b>
198<p></p>
199  No matter which will be the final book format, HTML is the preferred
200  format to use on the writing time. A snapshot of the current book
201  state can be done at any time, converting the sources to an HTML
202  page, so any system with a browser can read it. If you need a
203  printable version, convert the HTML to PDF with the excellent
204  <a href="http://www.easysw.com/htmldoc/">htmldoc</a> tool.
205<p></p>
206</li>
207<li><b>Book Contents Overview</b>
208<p></p>
209  To quickly have a global overview of the book contents at any time,
210  just use the txt2tags <i>TOC Only</i> feature. The program shows the
211  current Table of Contents for the book, with the listing of chapters
212  and sections, numbered or not, at any depth.
213<p></p>
214</li>
215<li><b>Fast Writing</b>
216<p></p>
217  Txt2tags marks are simple and minimalist, very easy to learn. No
218  names, no options, no parameters. You don't have to stop writing
219  contents to insert marks, they flow together with the text. If you
220  don't remember a specific mark at the moment, forget about it and
221  keep writing. At the end you do a global review on the text and
222  quickly insert the missing marks.
223<p></p>
224</li>
225<li><b>Fast Conversion</b>
226<p></p>
227  Even if you have a 500 pages book, the conversion process will take
228  just a moment. It is because txt2tags acts as a filter, converting
229  from one format to another. It does not index, compile, calculate,
230  compress, draw or do any strong processing on the sources. No more
231  library, catalog, schema and DTD nightmares.
232</li>
233</ul>
234
235<a id="toc5" name="toc5"></a>
236<h1>5. Organize the Sources in Folders</h1>
237<p>
238Txt2tags has a built in command to include external files in any part
239of a document, at conversion time. It makes possible to split the
240sources into several files.
241</p>
242<ul>
243<li><b>Each chapter in a folder</b>
244<p></p>
245  You can make a folder for each chapter, storing the sources in a
246  structured tree. Inside the chapter folder, you can even create
247  subfolders to store images, configuration and included files.
248<p></p>
249</li>
250<li><b>No file conflicts</b>
251<p></p>
252  Separating chapters, different teams can work in different chapters
253  with no interaction between them. Each team work on its own folder,
254  avoiding file conflicts due concurrent changes.
255<p></p>
256</li>
257<li><b>Flexible access control</b>
258<p></p>
259  Files and folders organized, you can implement access control rules,
260  setting up properties and permissions for any file or chapter. Do
261  use the standard system tools to configure the read/write
262  permissions, like the "users and groups" schema.
263<p></p>
264</li>
265<li><b>Global view of sources</b>
266<p></p>
267  Structuring the sources also helps to have a global view of the
268  book, using any file browser to quickly know the amount of text and
269  images of any chapter. (Hint: on UNIX, <code>find</code> and <code>du</code> commands)
270<p></p>
271</li>
272<li><b>Work your chapter, forget the others</b>
273<p></p>
274  Separating sources into files, you can convert your chapter alone,
275  not needing to wait for the full book processing. Besides faster
276  to convert, the chapter alone can be sent to reviewers or be
277  published alone, as a sample of the full book.
278<p></p>
279</li>
280<li><b>You separate, txt2tags joins</b>
281<p></p>
282  When converting, txt2tags will automatically join all the chapters
283  into the final book, no matter how deep or large is the folder
284  tree.
285</li>
286</ul>
287
288<a id="toc6" name="toc6"></a>
289<h1>6. Version Control Made Easy</h1>
290<p>
291Txt2tags helps the book version control with line based tools (as
292<i>CVS</i> and <i>Subversion</i>). The sources are plain text, not compiled
293data.
294</p>
295<ul>
296<li><b>Work with short lines</b>
297<p></p>
298  You can make short lines, breaking them at 72 columns. It will help
299  on the revision control, because it is line based. If the final
300  format needs that a paragraph is composed by a single long line (as
301  PageMaker), txt2tags will join them to you automatically.
302<p></p>
303</li>
304<li><b>Readable sources</b>
305<p></p>
306  With very minimal markup, the sources are readable. One can easily
307  see what has changed from one version to another, the marks don't
308  hide or pollute the text.
309<p></p>
310</li>
311<li><b>Large contents, small sources</b>
312<p></p>
313  As plain text, you can have a huge amount of contents, with a low
314  disk usage. People can do full checkouts and commits even in slow
315  connections.
316<p></p>
317</li>
318<li><b>Chapter versioning</b>
319<p></p>
320  As seen before, the sources can be organized into folders. This
321  makes version control separated by chapter, or even sections of
322  chapters, depending on how granulated you need the versioning.
323</li>
324</ul>
325
326<a id="toc7" name="toc7"></a>
327<h1>7. Quality Matters</h1>
328<p>
329You can write a book. Or you can write THE book. Txt2tags has nice
330built in features to increase your work quality.
331</p>
332<ul>
333<li><b>Spell Check</b>
334<p></p>
335  As all txt2tags marks are symbols and not words, you can use any
336  spell checker on the sources. It will take care of the text only,
337  not trying to correct tags.
338<p></p>
339</li>
340<li><b>Alias Database</b>
341<p></p>
342  Txt2tags has <i>Pre Processing Filters</i>, where you can define
343  keyword/value pairs. Wherever the keyword is found on the sources, it
344  is expanded to the given value at conversion time. For example, you
345  do use the string <code>URL_GOOGLE</code> on your text and it will appear as
346  <code>http://www.google.com</code> on the book. If the Google URL changes,
347  you just change the filter definition and all occurrences of it will
348  be updated. You can define as many keywords as needed, with no
349  maximum limit.
350<p></p>
351</li>
352<li><b>Dynamic Content</b>
353<p></p>
354  Txt2tags also has a command to include pre-formatted text into the
355  document when converting it, for example, a software source code
356  sample. This way you can keep this code sample separated from the
357  book text and update it by hand or even automatically. A nice idea
358  is to mark the software source code with special comments, and a
359  little program extract these marked parts into separate files.
360<p></p>
361</li>
362<li><b>Control Over the Result</b>
363<p></p>
364  Txt2tags has <i>Post Processing Filters</i>, where you can define rules
365  that makes adjustments on the resulting document. So if the standard
366  txt2tags conversion does not fully satisfy your needs, you can
367  improve it with your own filters. You can use the power of the
368  Regular Expressions to match patterns.
369</li>
370</ul>
371
372<a id="toc8" name="toc8"></a>
373<h1>8. Other Advantages</h1>
374<p>
375And there is more!
376</p>
377<ul>
378<li><b>Separate Formatting from Contents</b>
379<p></p>
380  Using HTML as the development target format, you can also use CSS
381  files to experiment different book looks. CSS defines formating for
382  HTML pages, and there is graphical editors to create CSS files.
383  A team of designers can work on doing CSS files for the book, while
384  the writers keep writing.
385<p></p>
386</li>
387<li><b>Include Complicated Structures</b>
388<p></p>
389  Txt2tags does have support for all the common structures used in
390  texts: lists, definitions, quotation, verbatim area and tables. But
391  if some parts of your book requires a more complicated structure,
392  you can use the <i>Tagged Include</i> feature, where you insert text
393  that is already tagged, like a real fancy HTML table. With txt2tags,
394  exceptions are not a problem!
395<p></p>
396</li>
397<li><b>Do Use Any Editor</b>
398<p></p>
399  As plain text source files, even the most modest text editor in the
400  world can be used to write the book. It doesn't have to have any
401  feature besides write and save text. If you use the editors with
402  txt2tags support, you will have <i>Syntax Highlight</i>, which helps to
403  identify the txt2tags marks. They are: Vim, Emacs, Kate, Nano, gedit
404  and TextMate.
405<p></p>
406</li>
407<li><b>Technical Support</b>
408<p></p>
409  Txt2tags has various channels to get technical support: two mailing
410  lists (english and portuguese), an IRC channel and even an Orkut
411  community. And for book projects, your can send direct e-mails to
412  the program author, who will give priority on the answer.
413</li>
414</ul>
415
416<a id="toc9" name="toc9"></a>
417<h1>9. No Tool Fits All Needs</h1>
418<p>
419There are some special cases where txt2tags is not a good tool for
420writing books.
421</p>
422<ul>
423<li><b>Very Complex Books</b>
424<p></p>
425  Books that uses lots of complicated tables, formulas or specific
426  structures, needs a graphical editor or a more complex markup
427  language, as LaTeX. If your book matches this description, txt2tags cannot help you.
428<p></p>
429</li>
430<li><b>Footnotes</b>
431<p></p>
432  Txt2tags does not have footnotes support. If you will use just a
433  few, you can add them later. But if you plan to make an intense
434  footnotes use, txt2tags cannot help you.
435<p></p>
436</li>
437<li><b>References for Pages, Tables and Images</b>
438<p></p>
439  One can use a graphical editor at the publishing time to include
440  indexes for pages, tables and images, no problem at all. But if you
441  plan to refer to them inside the text like
442  "<i>See table 4.11 on page 35</i>", txt2tags cannot help you.
443</li>
444</ul>
445
446<hr class="light" />
447<p>
448<i>Writing Books with Txt2tags - Oct/2004</i>
449(<a href="writing-book.t2t">see source</a>)
450</p>
451</div>
452
453<!-- xhtml code generated by txt2tags 2.6b (http://txt2tags.org) -->
454<!-- cmdline: txt2tags writing-book.t2t -->
455</body></html>