This repository has been archived by the owner on Dec 12, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 4
/
tips.html
1351 lines (1116 loc) · 41 KB
/
tips.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<meta name="author" content="Aurelio Jargas www.aurelio.net">
<META NAME="generator" CONTENT="http://txt2tags.org">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
<LINK REL="stylesheet" TYPE="text/css" HREF="inc/site.css">
<TITLE>txt2tags tips</TITLE>
<link rel="icon" type="image/png" href="/favicon.png">
</HEAD>
<BODY id="tips">
<DIV CLASS="header" ID="header">
<h1><a href="/">txt2tags</a></h1>
<H3>Tips & Tricks</H3>
</DIV>
<DIV CLASS="body" ID="body">
<div id="sidebar">
Hot
<ul>
<li id="menuonline"><a href="./online.php">Txt2tags Online</a></li>
<li id="menumarkup"><a href="./markup.html">Markup Demo</a></li>
</ul>
About
<ul>
<!-- <li id="menuhome"><a href="/">Home</a></li> -->
<li id="menufeatures"><a href="./features.html">Features</a></li>
<li id="menusample"><a href="./sample.html">Example</a></li>
<li id="menushots"><a href="./shots.html">Screenshots</a></li>
<li id="menudocs"><a href="./docs.html">Documentation</a></li>
<li id="menutips"><a href="./tips.html">Tips & Tricks</a></li>
<!--
<li id="menuoldnews"><a href="./misc/oldnews.html">Old News</a></li>
-->
</ul>
Code
<ul>
<li id="menudownload"><a href="./download.html">Download</a></li>
<li id="menuchangelog"><a href="./changelog.html">Changelog</a></li>
<li id="menutools"><a href="./tools.html">Tools</a></li>
<li><a href="https://github.com/txt2tags/txt2tags">GitHub</a></li>
</ul>
Community
<ul>
<li id="menuwiki"><a href="http://wiki.txt2tags.org">Wiki</a></li>
<li id="menublog"><a href="http://txt2tags.wordpress.com">Blog</a></li>
<li id="menuteam"><a href="./team/index.html">The Team</a></li>
<li id="menuchildren"><a href="./children.html">The Children</a></li>
<li id="menucomments"><a href="http://txt2tags.wordpress.com/user-comments/">User Comments</a></li>
<li id="menuart"><a href="./art.html">Artwork</a></li>
</ul>
Social
<ul>
<li id="menuml"><a href="./ml.html">Mailing List</a></li>
<li><a href="http://www.facebook.com/pages/txt2tags/335201827209">Facebook</a></li>
<!-- <li><a href="http://www.orkut.com.br/Main#Community?cmm=87935">Orkut</a></li> -->
</ul>
<P>
<A HREF="https://www.paypal.com/cgi-bin/webscr?cmd=_xclick&business=verde%40aurelio%2enet&item_name=txt2tags%20donation&no_shipping=1&return=http%3a%2f%2faurelio%2enet%2fdonate%2dthanks%2ehtml&cn=&tax=0&currency_code=USD&bn=PP%2dDonationsBF&charset=UTF%2d8"><IMG ALIGN="middle" SRC="img/donate.png" BORDER="0" alt="DONATE"></A>
</P>
</div>
<DIV CLASS="toc">
<UL>
<LI><A HREF="#general">General</A>
<UL>
<LI>1. <A HREF="#top-mistakes">Top 4 user mistakes</A>
<LI>2. <A HREF="#doc-tree">Quick document tree</A>
<LI>3. <A HREF="#strike">Make strike text</A>
<LI>4. <A HREF="#filter-icase">Make case insensitive filters</A>
<LI>5. <A HREF="#center-para">Make centred aligned paragraphs</A>
<LI>6. <A HREF="#link-bank">Use a link bank to keep your text clean</A>
<LI>7. <A HREF="#auto-link">Use automatic linking for "cristal clear" text</A>
<LI>8. <A HREF="#force-url">Force link (URL) recognition</A>
<LI>9. <A HREF="#image-unicode">Use spaces and Unicode characters in image filename</A>
<LI>10. <A HREF="#date-default-format">Change the default format for the %%date macro</A>
<LI>11. <A HREF="#code-syntax">Make code snippets colored (syntax highlight)</A>
<LI>12. <A HREF="#copyright-symbol">Insert copyright symbols: © ® ™</A>
<LI>13. <A HREF="#dump-config">Config overview (or Solving configuration problems)</A>
</UL>
<LI><A HREF="#target-specific">Target Specific</A>
<UL>
<LI>14. <A HREF="#col-align">Table COLUMN align targets: SGML, LaTeX and Man Page</A>
<LI>15. <A HREF="#css-sugar">(X)HTML: What exactly the --css-sugar option does</A>
<LI>16. <A HREF="#html-line-break">(X)HTML: Insert a manual line break <BR></A>
<LI>17. <A HREF="#html-semantic-tags">(X)HTML: Use semantic tags (STRONG, EM, INS, DEL) instead visual tags (B, I, U, S)</A>
<LI>18. <A HREF="#html-super-sub">(X)HTML: Make subscript/superscript text</A>
<LI>19. <A HREF="#html-remote-image">(X)HTML: Use a remote image</A>
<LI>20. <A HREF="#html-img-alt">(X)HTML: Insert text for images ALT attribute</A>
<LI>21. <A HREF="#html-custom-tags">(X)HTML: Insert custom tags (DIV, SPAN)</A>
<LI>22. <A HREF="#html-entities">(X)HTML: Use entities like &eacute; for accented characters</A>
<LI>23. <A HREF="#html-custom-tags">(X)HTML: Split the page in multiple files</A>
<LI>24. <A HREF="#html-to-t2t">(X)HTML: Convert HTML pages to the txt2tags markup</A>
<LI>25. <A HREF="#man-section">Man: Change section number</A>
<LI>26. <A HREF="#man-options">Man: Make the OPTIONS part of the man page</A>
<LI>27. <A HREF="#mgp-pause">MagicPoint: Make a pause on the slide</A>
<LI>28. <A HREF="#tex-style">LaTeX: Load extra packages (\usepackage)</A>
<LI>29. <A HREF="#tex-date">LaTeX: Remove the current date</A>
<LI>30. <A HREF="#tex-lang">LaTeX: Set the language config (babel, inputenc)</A>
<LI>31. <A HREF="#tex-user-style">LaTeX: Use a personal style file (.sty)</A>
<LI>32. <A HREF="#tex-greek">LaTeX: Use symbols and Greek letters (µ « ® Ø)</A>
</UL>
<LI><A HREF="#text-editors">Text Editors</A>
<UL>
<LI>33. <A HREF="#vim-convert">Vim: Convert the current file</A>
<LI>34. <A HREF="#vim-mappings">Vim: Handy mappings to convert files</A>
</UL>
</UL>
</DIV>
<P>
<A HREF="http://txt2tags.wordpress.com/2006/09/21/new-hot-document-tips-tricks/">Suggest a new tip!</A>
</P>
<H1 ID="general">General</H1>
<H2 ID="top-mistakes">1. Top 4 user mistakes</H2>
<OL>
<LI>Forget to close lists with <B>two</B> blank lines (or with an empty
item)
<PRE>
<b>BAD</b> <b>GOOD</b>
- My cool list - My cool list
- Should end here - Ends here
= No, not a title =
= Title =
</PRE>
<LI>Forget to "glue" the marks with their contents, leaving unwanted spaces
<PRE>
<b>BAD</b> <b>GOOD</b>
** not bold** **bold**
__not underline __ __underline__
// no way it is italic // //italic//
[invalid link ] [label link]
[ invalid_image.png ] [image.png]
</PRE>
<LI>Forget to add the required spaces around table cells
<PRE>
<b>BAD</b> <b>GOOD</b>
|no|it's|not|a|table| | this | is | a | table |
</PRE>
<LI>Forget to add leading spaces to identify nested lists
<PRE>
<b>BAD</b> <b>GOOD</b>
: definition list : definition list
- turned to bullet list? - bullet inside
+ and now it is numbered? + numbered inside bullet
- what a mess! - back to bullet
</PRE>
</OL>
<H2 ID="doc-tree">2. Quick document tree</H2>
<P>
Writing a long document and suddenly get lost? Needs to edit that 50
page monster you don't touch for months? There is a quick way to get
an overview of the contents:
</P>
<PRE>
$ <b>txt2tags --toc-only -t txt userguide.t2t</b>
Part I - Introducing Txt2tags
The First Questions You May Have
Supported Formatting Structures
Supported Targets
Status of Supported Structures by Target
The Three User Interfaces: Gui, Web and Command Line
Part II - OK, I want it. Now what?
Download & Install Python
Download txt2tags
...
</PRE>
<P>
The <CODE>--toc-only</CODE> option dumps the Table of Contents of the document,
using the same target as the document's. So we force it to be clear
text with <CODE>-t txt</CODE>. Another option that can be used is
<CODE>--enum-title</CODE> to get nice numbers:
</P>
<PRE>
$ <b>txt2tags --toc-only -t txt --enum-title userguide.t2t </b>
1. Part I - Introducing Txt2tags
1.1. The First Questions You May Have
1.2. Supported Formatting Structures
1.3. Supported Targets
1.4. Status of Supported Structures by Target
1.5. The Three User Interfaces: Gui, Web and Command Line
2. Part II - OK, I want it. Now what?
2.1. Download & Install Python
2.2. Download txt2tags
...
</PRE>
<P>
If the document tree is deep, you can limit the dump to any level with the <CODE>--toc-level</CODE> option:
</P>
<PRE>
$ <b>txt2tags --toc-only -t txt --enum-title --toc-level 1 userguide.t2t </b>
1. Part I - Introducing Txt2tags
2. Part II - OK, I want it. Now what?
3. Part III - Writing and Converting Your First Document
4. Part IV - Mastering Txt2tags Concepts
5. Part V - Mastering Marks
6. Part VI - Mastering Macros
7. Part VII - Mastering Settings
8. Part VIII - Black Magic
9. Part IX - Txt2tags HISTORY
</PRE>
<H2 ID="strike">3. Make strike text</H2>
<P>
Upgrade your txt2tags to version 2.5 or newer, which has strike text support with the <CODE>--</CODE> mark. For example, <CODE>--STRIKE--</CODE> becomes <s>STRIKE</s>.
</P>
<P>
In older versions, some nice filters will do the trick:
</P>
<PRE>
%%% Support for --strike-- text in txt2tags older than 2.5
%
%!postproc(html): '--([^ ].*?)--' <s>\1</s>
%
%!style(tex): ulem
%!postproc(tex): --(.*?)-- \sout{\1}
</PRE>
<P>
If you want to use this filter for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>
<H2 ID="filter-icase">4. Make case insensitive filters</H2>
<P>
<A HREF="userguide/PreProc.html">PreProc</A> and <A HREF="userguide/PostProc.html">PostProc</A> filters are case sensitive by default. This
means that when matching, the text "txt2tags" is different from
"TXT2TAGS". If you want to make a filter that treats lower and
uppercase letters as the same (ignore case), just put a "<CODE>(?i)</CODE>" at
the beginning. Example:
</P>
<PRE>
%preproc: '(?i)latex' 'LaTeX'
</PRE>
<P>
This way, "latex", "LATEX", "LAtex" and all its variants will be
changed to "LaTeX".
</P>
<H2 ID="center-para">5. Make centred aligned paragraphs</H2>
<P>
In txt2tags you can't center paragraphs, but you can center a table.
So...
</P>
<PRE>
| This is a centered paragraph.
</PRE>
<P>
This line results in:
</P>
<TABLE ALIGN="center">
<TR>
<TD>This is a centered paragraph.</TD>
</TR>
</TABLE>
<P>
<B>Note:</B> There are spaces before the pipe <CODE>|</CODE> to make the table centred. There
are no trailing pipe at the end of the line, so this table has no
border, making it invisible.
</P>
<P>
<B>Note:</B> Yes, this is ugly and piggy. Avoid to use it.
</P>
<P>
<B>Note:</B> In (X)HTML targets, it's best to
<A HREF="#html-custom-tags">enclose the paragraph inside a DIV</A> and make a CSS
rule to center it.
</P>
<H2 ID="link-bank">6. Use a link bank to keep your text clean</H2>
<P>
If your document will use many links (URLs), the text can quickly become too
noisy and polluted. The cleaner approach is to store all the links at
the <A HREF="userguide/ConfigArea.html">config area</A>, making a link bank:
</P>
<PRE>
%!preproc: URLT2T http://txt2tags.org
%!preproc: URLGOOGLE http://google.com?q=txt2tags+is+cool
%!preproc: URLBLOG http://myblog.wordpress.com/2006/10/31/foo-bar-baz
</PRE>
<P>
Then you can write your text with cleaner links:
</P>
<PRE>
This site is powered by [txt2tags URLT2T]. For more information
please [read my Blog URLBLOG] or [search Google URLGOOGLE].
</PRE>
<P>
Compare this to the inline links (ugly) version:
</P>
<PRE>
This site is powered by [txt2tags http://txt2tags.org].
For more information please
[read my Blog http://myblog.wordpress.com/2006/10/31/foo-bar-baz]
or [search Google http://google.com?q=txt2tags+is+cool].
</PRE>
<P>
<B>Plus:</B> If there are links that you use all the time in your
documents (your website or blog, for example), you can make a global
link bank on an urls.t2t file, or on your
<A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>, then
all your documents can use them. The other advantage is that it makes
easy when the link changes, you just have to edit one single place.
</P>
<H2 ID="auto-link">7. Use automatic linking for "cristal clear" text</H2>
<P>
An evolution from the previous tip, you can put links automatically
for any word(s) you want.
</P>
<PRE>
%!preproc: '(?i)(txt2tags)' '[\1 http://txt2tags.org]'
%!preproc: '(Google)' '[\1 http://google.com]'
%!preproc: '(Yahoo! Groups)' '[\1 http://groups.yahoo.com]'
</PRE>
<P>
Then in your text you won't bother inserting links manually, txt2tags
will do it for you:
</P>
<PRE>
I do use Txt2tags, Google and Yahoo! Groups everyday.
</PRE>
<P>
Converting this text to XHTML:
</P>
<PRE>
<p>
I do use <a href="http://txt2tags.org">Txt2tags</a>,
<a href="http://google.com">Google</a> and
<a href="http://groups.yahoo.com">Yahoo! Groups</a> everyday.
</p>
</PRE>
<P>
Handy, huh? Note that the "<CODE>(?i)</CODE>" part on the first filter make it
<A HREF="#filter-icase">case insensitive</A>, working for "txt2tags", "TXT2TAGS"
and any other variant.
</P>
<H2 ID="force-url">8. Force link (URL) recognition</H2>
<P>
When trying (and failing) to make some funky links like:
</P>
<PRE>
[Main page index.php?page=main]
[Product details product?id=1234567]
</PRE>
<P>
Just "protect" the link address with the raw mark and it will be converted correctly:
</P>
<PRE>
[Main page ""index.php?page=main""]
[Product details ""product?id=1234567""]
</PRE>
<P>
<B>Note:</B> This is often needed for local (relative) links only. Full URLs like <A HREF="http://www.example.com/product?id=1234567">www.example.com/product?id=1234567</A> are recognized by default.
</P>
<H2 ID="image-unicode">9. Use spaces and Unicode characters in image filename</H2>
<P>
We need to be restrictive to avoid false positives when matching texts. These are the currently allowed characters for an image filename:
</P>
<PRE>
A-Za-z0-9_,.+%$#@!?+~/-
</PRE>
<P>
If your image filename contains spaces, accented letters or Unicode characters, just protect the filename (except the extension!) with the raw mark:
</P>
<PRE>
[""image中文"".jpg]
</PRE>
<H2 ID="date-default-format">10. Change the default format for the %%date macro</H2>
<P>
When used without arguments, the <A HREF="userguide/date.html">%%date macro</A> expands to the current date in the ISO format: <CODE>YYYYMMDD</CODE>. But with a nice filter, you can change this default format:
</P>
<PRE>
%!preproc: %%date %%date(%d-%m-%Y %H:%M)
</PRE>
<P>
If you want to use this filter for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>
<H2 ID="code-syntax">11. Make code snippets colored (syntax highlight)</H2>
<P>
Txt2tags doesn't colorize programming code inside verbatim blocks.
That would be plain bloat, and we're KISS.
</P>
<P>
But you can make that using any other colorizer program and save the
results to a file. Then you just include this file on the txt2tags
conversion using the <A HREF="userguide/includecommand.html">Tagged Include</A>
feature.
</P>
<PRE>
%!include(html): ''colorized-file.py.html''
</PRE>
<P>
If you use the <A HREF="http://vim.org">Vim editor</A>, just run this command to
get you code colorized in HTML (check the path for 2html.vim on your
system):
</P>
<PRE>
vi -c "so /usr/share/vim/vim7/syntax/2html.vim|wqa" file.py
</PRE>
<H2 ID="copyright-symbol">12. Insert copyright symbols: © ® ™</H2>
<P>
You can enter the © and ® symbols directly on the source file without fuss. Just find out how to insert them in your text editor. Copy & paste also works fine (copy from here!).
</P>
<BLOCKQUOTE>
<B>Note:</B>
In Vim, type <CODE>Ctrl-K Co</CODE> and <CODE>Ctrl-K Rg</CODE> in Insert mode.
The :dig command lists other symbols.
</BLOCKQUOTE>
<P>
Depending on the target, you may have to specify a new file encoding so that these symbols appear correctly. If you run into problems, try adding this line to your configuration:
</P>
<PRE>
%!encoding: iso-8859-1
</PRE>
<P>
The ™ symbol is a little trickier because it's part of the new UTF-8 encoding. First you need to save your source file as an UTF-8 text file. Check your text editor's preferences. Then just tell txt2tags about the new encoding:
</P>
<PRE>
%!encoding: utf-8
</PRE>
<P>
<B>Bonus Tip:</B> If you plan to type symbols or accented characters in your texts, a good practice is always use the UTF-8 encoding in your files. You don't need to understand exactly what it is, just keep in mind that is has all the symbols you may need someday :)
</P>
<P>
Another solution is to use the target's specific characters entities that represent those symbols. Then you can insert those symbols as "(C)", "(R)" and "(TM)" on the source file and let the filters do the dirty job. But remember that each target must have its own set of filters. An example for HTML:
</P>
<PRE>
% Filters to use (C), (R) and (TM) as copyright symbols
%!postproc(html): \(C\) &copy;
%!postproc(html): \(R\) &reg;
%!postproc(html): \(TM\) &#8482;
</PRE>
<H2 ID="dump-config">13. Config overview (or Solving configuration problems)</H2>
<P>
In txt2tags you can
<A HREF="userguide/ConfigurationLoadingOrderandPrecedence.html">define configuration in three tiers</A>:
</P>
<UL>
<LI>The user configuration file (RC)
<LI>The source document <A HREF="userguide/ConfigArea.html">Config Area</A>
<LI>The command line options
</UL>
<P>
Things can get real wild if you make lots of configs in all those
places. Even wilder if you're using the
<A HREF="userguide/includeconfcommand.html">%!includeconf command</A>
to get more configuration to your document.
</P>
<P>
In doubt or trouble, use the <CODE>--dump-config</CODE> option to see all the
configuration that is being read. First it lists all the config found
on the RC file:
</P>
<PRE>
$ <b>txt2tags --dump-conf userguide.t2t</b>
RAW config for RC file
(all) target........: html
</PRE>
<P>
Then there is the config found on the document's <A HREF="userguide/ConfigArea.html">Config Area</A>. Note
that the first column shows the target where the config will be
applied. If it is "(all)", this config is valid for all targets.
</P>
<PRE>
RAW config for source document
(all) target........: html
(all) options.......: --toc --toc-level 2 --css-sugar
(all) options.......: --css-sugar --no-toc --style userguide.css
(all) postproc......: ('<H3>Aurelio, .*', '')
(all) preproc.......: ('IMGPATH', '.')
...
(html) preproc.......: ('^%nopdf', '')
(html) preproc.......: ('^ *--------*', '')
(html) preproc.......: ('^ *========*', '')
</PRE>
<P>
Next are the command line options:
</P>
<PRE>
RAW config for command line
(all) dump-config...: ON
(all) infile........: userguide.t2t
(all) realcmdline...: ['--dump-conf', 'userguide.t2t']
</PRE>
<P>
And after all this listing, here is the result: the parsed config.
It's the real configuration that will be applied to the document
after all the configs were read and processed.
</P>
<PRE>
Full PARSED config
css-sugar.....: ON
dump-config...: ON
infile........: userguide.t2t
realcmdline...: --dump-conf, userguide.t2t
sourcefile....: userguide.t2t
style.........: userguide.css
target........: html
toc-level.....: 2
Active filters
preproc.......: IMGPATH -> .
preproc.......: MARKPROP -> **Properties:**
preproc.......: MARKCONT -> **Contains:**
...
preproc.......: ^%nopdf ->
preproc.......: ^ *--------* ->
preproc.......: ^ *========* ->
postproc......: <H3>Aurelio, .* ->
</PRE>
<H1 ID="target-specific">Target Specific</H1>
<H2 ID="col-align">14. Table COLUMN align targets: SGML, LaTeX and Man Page</H2>
<P>
Some targets let you align each table cell independently, as HTML.
Other are more strict, just letting you align the table column, then
all its cells share the same positioning. This is the case for SGML,
LaTeX and Man.
</P>
<P>
On this targets, the column alignment is defined by the align of the
<B>first</B> table row cells (usually it's a title row). So keep that in
mind when writing your text.
</P>
<PRE>
| Name | Age |
| John Smith | 55 |
| Mary Katana | 23 |
</PRE>
<P>
In this example, both columns will be centered on the aforementioned
targets, regardless the left and right align defined on the second and
third rows.
</P>
<H2 ID="css-sugar">15. (X)HTML: What exactly the --css-sugar option does</H2>
<P>
It "insert CSS-friendly tags for HTML and XHTML targets" ;)
</P>
<P>
Ok, ok, more details:
</P>
<UL>
<LI>The CELLPADDING attribute is removed from TABLE tag
<LI>The HR tags around Table of Contents (TOC) are removed
<LI>The Table of Contents is placed inside the new "toc" DIV
<LI>The page contents (except TOC) is placed inside the new "body" DIV
<LI>The PRE tag contents is not indented by two spaces
<LI>The headers (first three lines) are changed:
<UL>
<LI>They are placed inside the new "header" DIV
<LI>They use H1, H2 and H3 tags with no formatting
</UL>
</UL>
<P>
So this option clears the formatting attributes and create new DIVs to
make it easier to use CSS rules. Then you can see the page as a three
piece component: header, toc, body and apply different rules for each.
</P>
<P>
<B>Note:</B> Using <CODE>--style</CODE> doesn't imply <CODE>--css-sugar</CODE>. You have to
declare both.
</P>
<H2 ID="html-line-break">16. (X)HTML: Insert a manual line break <BR></H2>
<P>
Txt2tags doesn't have a mark for the manual line break. In the cases
you want to use it, maybe a bullet list, a table or a verbatim text
would fit better.
</P>
<P>
But if the line break is the solution you want, just make your own new
mark for it. Let's say "@@" will be the line break mark.
</P>
<PRE>
%!postproc( html): @@ <BR>
%!postproc(xhtml): @@ <br />
</PRE>
<P>
Then in your text, use @@ when you want a line break. Example:
</P>
<PRE>
First line @@ Second Line @@ Third line
</PRE>
<H2 ID="html-semantic-tags">17. (X)HTML: Use semantic tags (STRONG, EM, INS, DEL) instead visual tags (B, I, U, S)</H2>
<P>
By default txt2tags uses the good old visual tags (<CODE><B></CODE>, <CODE><I></CODE>, <CODE><U></CODE>, <CODE><S></CODE>) for bold, italic, underline and strike text.
</P>
<P>
Some people prefer to use their semantic equivalents (<CODE><strong></CODE>, <CODE><em></CODE>, <CODE><ins></CODE>, <CODE><del></CODE>) instead. If this is your case, just set up these filters:
</P>
<PRE>
% Use semantic tags (strong, em, ins, del) instead visual (B, I, U, S)
%!postproc(html): '(?i)(</?)b>' '\1strong>'
%!postproc(html): '(?i)(</?)i>' '\1em>'
%!postproc(html): '(?i)(</?)u>' '\1ins>'
%!postproc(html): '(?i)(</?)s>' '\1del>'
</PRE>
<P>
If you want to use this filter for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>
<H2 ID="html-super-sub">18. (X)HTML: Make subscript/superscript text</H2>
<P>
Txt2tags doesn't have a mark for subscript or superscript text.
But you can make your own. Let's define the following two new marks
for them:
</P>
<UL>
<LI><B><CODE>^^text^^</CODE></B> for superscript text
<P></P>
<LI><B><CODE>,,text,,</CODE></B> for subscript text
</UL>
<P>
Using the same idea from the previous tip, we make two filters:
</P>
<PRE>
% The ^ need to be escaped by \
%!postproc(html): \^\^(.*?)\^\^ <sup>\1</sup>
%!postproc(html): ,,(.*?),, <sub>\1</sub>
</PRE>
<P>
Using this filters, <CODE>^^upper^^ and ,,lower,,</CODE> becomes
<CODE><sup>upper</sup> and <sub>lower</sub></CODE>.
</P>
<P>
Again, you can instead use the modern CSS powered version:
</P>
<PRE>
%!postproc(html): \^\^(.*?)\^\^ <span class="textsup">\1</span>
%!postproc(html): ,,(.*?),, <span class="textsub">\1</span>
% On the CSS:
% .textsup { vertical-align: super }
% .textsub { vertical-align: sub }
</PRE>
<P>
If you want to use this filters for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>
<H2 ID="html-remote-image">19. (X)HTML: Use a remote image</H2>
<P>
In txt2tags you have a mark for local images, but not for remote ones.
The trick here is to fool the program making it think your remote
image is local.
</P>
<P>
There are two ways of achieving this. The first uses a filter:
</P>
<PRE>
%!postproc(html): RemoteImage.jpg http://www.example.com/myimage.jpg
Hi, check out my picture: [RemoteImage.jpg].
</PRE>
<P>
So txt2tags will make the image tag <CODE><IMG SRC="RemoteImage.jpg"></CODE>
and the filter will change it to <CODE><IMG SRC="http://www.example..."></CODE>.
</P>
<P>
The other trick is cleaner to type, but relies on a txt2tags behavior
that may not work on future versions. Just protect the image address
with the <A HREF="userguide/RawRawLineRawArea.html">raw mark</A>, from the
beginning to the last character before the dot:
</P>
<PRE>
Hi, check out my picture: [""http://www.example.com/myimage"".jpg].
</PRE>
<P>
Easy!
</P>
<H2 ID="html-img-alt">20. (X)HTML: Insert text for images ALT attribute</H2>
<P>
Txt2tags already puts an empty ALT="" attribute on all images, so all
you have to do is to fill it. <A HREF="userguide/PostProc.html">PostProc</A> comes for the rescue.
</P>
<PRE>
%!postproc(xhtml): '(?i)(city.jpg.*?alt=")' '\1this is my city'
%!postproc(xhtml): '(?i)(beach.jpg.*?alt=")' '\1a really nice beach'
Hello, this is a photo of my city: [city.jpg]
And this the beach near here: [beach.jpg]
</PRE>
<P>
This will be converted to:
</P>
<PRE>
<p>
Hello, this is a photo of my city:
<img align="right" src="city.jpg" border="0" alt="this is my city"/>
And this the beach near here:
<img align="right" src="beach.jpg" border="0" alt="a really nice beach"/>
</p>
</PRE>
<P>
The <A HREF="userguide/PostProc.html">PostProc</A> rule is a
<A HREF="http://en.wikipedia.org/wiki/Regular_expression">regular expression</A>
that matches from the image filename until its ALT attribute contents
start. Don't worry if you don't understand these symbols. Just copy &
paste these lines to you text and change "<B>city.jpg</B>" by your image
filename and "<B>this is my city</B>" to the image's text. The rest remains
untouched.
</P>
<H2 ID="html-custom-tags">21. (X)HTML: Insert custom tags (DIV, SPAN)</H2>
<P>
From txt2tags version 2.6 and newer, there's a new tagged mark to
directly insert target code.
</P>
<P>
You can do it in blocks:
</P>
<PRE>
'''
<div id="mycooldiv">
This paragraph will live inside mycooldiv DIV.
But note that txt2tags marks are not interpreted here.
</div>
'''
</PRE>
<P>
In specific lines:
</P>
<PRE>
''' <div id="mycooldiv">
This paragraph will live inside mycooldiv DIV.
Txt2tags marks are interpreted here.
''' </div>
</PRE>
<P>
Or even inline, inside a paragraph:
</P>
<PRE>
My name is ''<span class="name">''John''</span>''.
</PRE>
<P>
If you're using and older version of txt2tags, follow these tips:
</P>
<P>
You can combine the <A HREF="userguide/RawRawLineRawArea.html">Raw Line mark</A>
and a <A HREF="userguide/PostProc.html">PostProc</A> filter to insert any arbitrary (X)HTML tag you need.
</P>
<P>
First, decide which symbols you'll use to represent the <CODE><</CODE> and
<CODE>></CODE> characters. A popular choice is <CODE>{{</CODE> and
<CODE>}}</CODE>. Then write your tags inside Raw Lines and it will work.
Example:
</P>
<PRE>
%!postproc(html): {{(.*?)}} <\1>
""" {{div id="mycooldiv"}}
This paragraph will live inside mycooldiv DIV.
""" {{/div}}
</PRE>
<P>
This will generate the following HTML code:
</P>
<PRE>
<div id="mycooldiv">
<P>
This paragraph will live inside mycooldiv DIV.
</P>
</div>
</PRE>
<P>
<B>Note:</B> The blank line after the paragraph is to make sure it will be closed before the DIV. If omitted, you'll end with tag overlap: <CODE><div><p></div></p></CODE>.
</P>
<H2 ID="html-entities">22. (X)HTML: Use entities like &eacute; for accented characters</H2>
<P>
All modern browsers know how to handle accented characters, you don't need to use HTML entities like <CODE>&eacute;</CODE> or <CODE>&atilde;</CODE> to represent them. Just type the accented letters normally.
</P>
<P>
The only thing you need to do, is to specify the correct encoding of your source file. You can use the txt2tags <CODE>--encoding</CODE> option or <CODE>%!encoding</CODE> directive. Examples:
</P>
<PRE>
% My source file is encoded in UTF-8
%!encoding: UTF-8
% My source file is encoded in latin-1 (ISO-8859-1)
%!encoding: iso-8859-1
</PRE>
<P>
If you really need the entities, for some exotic reason or system limitation, you can convert the accented chars using filters. If you use just a few accented chars, create one filter for each letter (lower and uppercase):
</P>
<PRE>
% Convert accented chars to HTML entities: é -> &eacute;
%!postproc(html): á &aacute;
%!postproc(html): â &acirc;
%!postproc(html): à &agrave;
%!postproc(html): ã &atilde;
%!postproc(html): ä &auml;
%!postproc(html): Á &Aacute;
% ...
</PRE>
<P>
If you want a general solution for all accented vowels plus C-cedilla and N-tilde, use this set of filters:
</P>
<PRE>
% Convert accented vowels (plus Ç and Ñ) to HTML entities
%!postproc(html): ([ÁÉÍÓÚáéíóú]) &\1acute;
%!postproc(html): ([ÀÈÌÒÙàèìòù]) &\1grave;
%!postproc(html): ([ÄËÏÖÜäëïöü]) &\1uml;
%!postproc(html): ([ÂÊÎÔÛâêîôû]) &\1circ;
%!postproc(html): ([ÃÕãõ]) &\1tilde;
%!postproc(html): &[ÁÀÃÄÂ](\w+;) &A\1
%!postproc(html): &[áàãäâ](\w+;) &a\1
%!postproc(html): &[ÉÈËÊ](\w+;) &E\1
%!postproc(html): &[éèëê](\w+;) &e\1
%!postproc(html): &[ÍÌÏÎ](\w+;) &I\1
%!postproc(html): &[íìïî](\w+;) &i\1
%!postproc(html): &[ÓÒÖÔÕ](\w+;) &O\1
%!postproc(html): &[óòöôõ](\w+;) &o\1
%!postproc(html): &[ÚÙÜÛ](\w+;) &U\1
%!postproc(html): &[úùüû](\w+;) &u\1
%!postproc(html): Ñ &Ntilde;
%!postproc(html): ñ &ntilde;
%!postproc(html): Ç &Ccedil;
%!postproc(html): ç &ccedil;
</PRE>
<P>
If you want to use this filters for all your files, put it on the <A HREF="userguide/UserConfigurationFileRCFile.html">txt2tags RC File</A>.
</P>
<H2 ID="html-custom-tags">23. (X)HTML: Split the page in multiple files</H2>
<P>
All you have to do is to normally convert your file to (X)HTML with
txt2tags, then use the excellent HTMLDOC tool to split it. Example:
</P>
<PRE>
htmldoc -t htmlsep -o output-folder file.html
</PRE>
<P>
You can get full instructions on how to install and use HTMLDOC with
txt2tags on
<A HREF="http://txt2tags.wordpress.com/2006/08/31/split-html-in-multiple-pages/">this Blog post</A>.
</P>
<H2 ID="html-to-t2t">24. (X)HTML: Convert HTML pages to the txt2tags markup</H2>
<P>
If you're migrating your site to txt2tags, there's a handy Vim script to convert all your HTML files to the simple t2t markup.
</P>
<UL>
<LI>First download the <A HREF="tools/unhtml.vim">unhtml.vim</A> script, or get it from the txt2tags "extras" folder.
<P></P>
<LI>Then open one HTML file on the <A HREF="http://www.vim.org">Vim editor</A> and execute the following command:
<PRE>
:source /path/to/unhtml.vim
</PRE>
<P></P>
<LI>A new txt2tags file named <CODE><yourfile>.html.t2t</CODE> will be saved. Check its contents and correct by hand any mistake.
</UL>
<P>
Repeat this process to all your HTML files.
</P>