PageRenderTime 29ms CodeModel.GetById 21ms app.highlight 3ms RepoModel.GetById 2ms app.codeStats 0ms

/doc/English/writing-book.t2t

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