2 ==================================================================================
3 Copyright (c) 2019-2020 Nokia
4 Copyright (c) 2018-2020 AT&T Intellectual Property.
6 Licensed under the Apache License, Version 2.0 (the "License");
7 you may not use this file except in compliance with the License.
8 You may obtain a copy of the License at
10 http://www.apache.org/licenses/LICENSE-2.0
12 Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS,
14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 See the License for the specific language governing permissions and
16 limitations under the License.
17 ==================================================================================
22 Abstract: This file provides macros allowing {X}fm source to generate
23 rts input from {X}fm source when the doc is passed through
24 tfm, and to generate postscirpt output when passed through
25 pfm. Simalar to the roff.im macro set that allows the generation
26 of troff input for man pages.
28 Author: E. Scott Daniels
32 Maybe useful (but doesn't explain why real formatters aren't being used)
33 http://docutils.sourceforge.net/docs/user/rst/quickref.html
37 .** convert {X}fm input into rts.
38 .** post processing is needed to strip the leading space that tfm insists on adding.
40 .** character offsets needed to provide bloody indention significant crap.
41 .** tfm converts points to characters using 7p/ch so these guarentee correct
51 .** Long strings of equals and dashes needed to make title/subtitle easier to generate. Multi
52 .** line annotations for headers could be used, but the code is messy for what results in
53 .** 4 lines in the setup files. CAUTION: tildas must be quoted with back-ticks.
55 .dv many_equals ============================================================================================
56 .dv many_dashes --------------------------------------------------------------------------------------------
57 .dv many_tildas `^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`
62 .** tfm version 2.0.0+ supports header annotation for rst
63 .dh 1 a==after s=2,1 i=0 m=0
64 .dh 2 a=-after s=2,1 i=0 m=0
65 .dh 3 a=~after s=2,0 i=0 m=0
71 .dv __alert ### WARNING ### rst.im detects an old(er) version of tfm some formatting might not be right (&_major)
78 .dv h1 .sp 1 $1 .br &many_equals .sp 1
79 .dv h2 .sp 1 $1 .br &many_dashes .sp 1
80 .dv h3 .sp 1 $1 .br &many_tildas .sp 1
83 .dv cd 1 &{col_width!8.0i} m=0i
91 .dv nf .sp 1 ^:^: .br .ll -2 .in +2
92 .dv fo .in -2 .ll +2 .sp 1
97 .** list item characters
102 .in 0i .** bloody rst is indention sensitive like markdown; sheesh
104 .dv esc \$1 : .** bloody need to escape _ and * at the end of a word
109 .dv mult_space .sp $1
111 .** ------- bullet lists -------------------------
112 .dv beg_list .sp 1 .bl ${1!*} ^: .br
113 .dv end_list .el .sp 1
117 .dv ex_start .sp 1 ^:^: .sp 1 .ll -2 .in +2 .nf
118 .dv ex_end .fo on .in -2 .ll +2 .sp 1
119 .dv ex_end_fig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
120 .dv ex_end_cfig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
122 .dv proto_start .sp 1 .cc .5i .st 9 .sf Courier-bold .nf
123 .dv proto_end .fo on .sf ^&text_font .st ^&text_size .sp .3
125 .dv center .br $1 .br
126 .dv center_start ^.. class:: center .br
129 .** fonts and font macros
132 .dv cw ^^^`^^^`$1^^^`^^^`
133 .** global font changes seem impossible in RST
136 .dv super .sm ^[ .sm ^&{ss_num}]
138 .dv note .dv ss_num ^[ ?%.0f ^&ss_num 1 + ] ^: .sm ^^[^&{ss_num}]
139 .** rst has no concept of a page, so all notes go to the close of the doc
143 .** ----------- definition lists and tables ------------------------------------
145 A list table without borders should build a reasonable def list in
146 RST. What RST touts as a def list turns out looking like crap, so we
147 jump some hoops to generate a two column table.
148 The usual pratcice of adding half space between items is ignored
149 by rst, and we add addtional "logic" to insert a blank line betwen
150 rows in order to visually separate the entries. Better than the default
151 but certainly not great. The output of these macros is extreamely space
152 sensitive (leading spaces because python programmers believe these
153 kinds of "everythign must align" parsers are good).
155 It seems that not all HTML generated from RST is done consistently. As an example
156 the HTML generated for read the docs does NOT respect the no boarder option
157 on tables, and adds additional space at the bottom of each table. Thus there
158 are two sets of definition list macros; by default the RTD style of ignoring
159 directives is assumed. The alternate set can be enabled by setting the variable
160 'sane_dlist' before imbedding this definition file.
162 When sane_dlist is set to 1, definition list items will be separated with a row
163 separater applied at the start of rows 2-n.
165 RST requires a blank line prior to the start of the list, so we force one.
168 .** beg_dlist parms 1 and 2 are for PFM, $3 is for rst and is optionally the term,def widths (e.g. 15,80)
169 .** mind the tildas (end of line escapes in {X}fm
171 .if &{sane_dlist!0} 1 =
172 .dv beg_dlist .dv di_term 1 ^: ~
173 .dv row_sep .sp 1 ^: ~
176 ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0 .br ^:class^: borderless ~
179 .dv ditem ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
180 .dv ditem_nosp .in -&{_ch4} * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
182 .dv di ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
183 .dv diitem ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
186 .dv beg_dlist .dv di_term 1 ^: ~
187 .dv row_sep .sp 1 ^: ~
190 ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0 .br ^:class^: borderless ~
193 .dv ditem ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
194 .dv ditem_nosp ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
195 .dv di ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
196 .dv diitem ^&row_sep * - **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
199 .** auto numbering ditem has to be hacked in since we're completely unable to use {X}fm's list gen for RST
200 .dv aditem ^&row_sep .in &_ch6 * - **^&{di_term}** .in &_ch8 - .in &_ch10 .dv row_sep .sp 1 | .sp 1 ^: .dv di_term ^[ %.0f ^&di_term 1 + ]
202 .dv end_dlist .sp 1 .in -&{_ch10} .sp 1
204 .** generate a table with borders
205 .dv beg_table ^.. list-table^:^: .br ^` ^` ^:widths^: $1 .br ^` ^` ^:header-rows^: 0 .sp 1
207 .** generate a table without borders
208 .dv beg_table_nb ^.. list-table^:^: .br ^` ^` ^:widths^: $1 .br ^` ^` ^:header-rows^: 0 .br ^` ^` ^:class^: borderless .sp 1
210 .** remainder of table support commands not dependent on borders/borderless
211 .dv col .in 0i .br ^` ` -` ^` .in 56p
212 .dv row .in 0i .sp 1 ^` ` * -` ^` .in 56p
213 .dv end_table .sp 1 .in 0i