doc/src/rst.im

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019-2020 Nokia
   4         Copyright (c) 2018-2020 AT&T Intellectual Property.
   5
   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
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  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 ==================================================================================
  18 .fi
  19
  20 .if false
  21         Mnemonic:       rts.im
  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.
  27
  28         Author:         E. Scott Daniels
  29         Date:           7 February 2019
  30
  31
  32                 Maybe useful (but doesn't explain why real formatters aren't being used)
  33                 http://docutils.sourceforge.net/docs/user/rst/quickref.html
  34 .fi
  35
  36
  37         .** convert {X}fm input into rts.
  38         .** post processing is needed to strip the leading space that tfm insists on adding.
  39
  40         .** character offsets needed to provide bloody indention significant crap.
  41         .** tfm converts points to characters using 7p/ch so these guarentee correct
  42         .** spacing.
  43         .**
  44         .dv _ch2 14p
  45         .dv _ch4 28p
  46         .dv _ch6 42p
  47         .dv _ch8 56p
  48         .dv _ch10 70p
  49
  50         .** Long strings of equals and dashes needed to make title/subtitle easier to generate. Multi
  51         .** line annotations for headers could be used, but the code is messy for what results in
  52         .** 4 lines in the setup files.
  53         .**
  54         .dv many_equals ============================================================================================
  55         .dv many_dashes --------------------------------------------------------------------------------------------
  56         .dv many_tildas ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  57
  58         .gv semver
  59         .if &_major 1 >
  60                 .** tfm version 2.0.0+ supports header annotation for rst
  61                 .dh 1 a==after s=2,1 i=0 m=0
  62                 .dh 2 a=-after s=2,1 i=0 m=0
  63                 .dh 3 a=~after s=2,0 i=0 m=0
  64
  65                 .dv h1 .h1 $1
  66                 .dv h2 .h2 $1
  67                 .dv h3 .h2 $1
  68         .ei
  69                 .dv __alert ### WARNING ###  rst.im detects an old(er) version of tfm some formatting might not be right
  70                 .sv __alert
  71
  72                 .dh 1 s=2,1 i=0 m=0
  73                 .dh 2 s=1.1 i=0 m=0
  74                 .dh 3 s=1,0 i=0 m=0
  75
  76                 .dv h1 .sp 1 $1 .br &many_equals .sp 1
  77                 .dv h2 .sp 1 $1 .br &many_dashes .sp 1
  78                 .dv h3 .sp 1 $1 .br &many_tildas .sp 1
  79         .fi
  80
  81         .dv cd 1 &{col_width!8.0i} m=0i
  82
  83         .dv h4 **$1**
  84
  85         .dv fig .fg $1
  86         .dv fig_cen .fg $1
  87         .dv set_font_cw
  88
  89         .dv nf  .sp 1 ^:^: .br .ll -2 .in +2
  90         .dv fo  .in -2 .ll +2 .sp 1
  91
  92         .dv indent
  93         .dv uindent
  94
  95         .** list item characters
  96         .dv lic1 *
  97         .dv lic2 -
  98         .dv lic3 +
  99
 100         .in 0i                                          .** bloody rst is indention sensitive like markdown; sheesh
 101
 102         .dv esc \$1 : .** bloody need to escape _ and * at the end of a word
 103         .dv line_len .ll $1
 104         .dv space .sp 1
 105         .dv half_space .sp 1
 106         .dv break .br |
 107         .dv mult_space .sp $1
 108
 109         .** ------- bullet lists -------------------------
 110         .dv beg_list .sp 1 .bl ${1!*} ^: .br
 111         .dv end_list .el .sp 1
 112         .dv li .br .li
 113         .dv item .br .li
 114
 115         .dv ex_start .sp 1 ^:^: .sp 1 .ll -2 .in +2 .nf
 116         .dv ex_end .fo on .in -2 .ll +2 .sp 1
 117         .dv ex_end_fig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
 118         .dv ex_end_cfig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
 119
 120         .dv proto_start .sp 1 .cc .5i .st 9 .sf Courier-bold .nf
 121         .dv proto_end .fo on .sf ^&text_font .st ^&text_size .sp .3
 122
 123         .dv center .br $1 .br
 124         .dv center_start ^.. class:: center .br
 125         .dv center_end .sp 1
 126
 127         .** fonts and font macros
 128         .dv ital *$1*
 129         .dv bold **$1**
 130         .dv cw ^^^`^^^`$1^^^`^^^`
 131         .** global font changes seem impossible in RST
 132         .dv set_font_prop
 133
 134         .dv super .sm ^[ .sm ^&{ss_num}]
 135         .dv ss_num 1
 136         .dv note .dv ss_num ^[ ?%.0f ^&ss_num 1 + ] ^: .sm ^^[^&{ss_num}]
 137         .** rst has no concept of a page, so all notes go to the close of the doc
 138         .dv atbot atclose
 139
 140
 141         .** ----------- definition lists and tables ------------------------------------
 142         .if false
 143                 A list table without borders should build a reasonable def list in
 144                 RST. What RST touts as a def list turns out looking like crap, so we
 145                 jump some hoops to generate a two column table.
 146                 The usual pratcice of adding half space between items is ignored
 147                 by rst, and we add addtional "logic" to insert a blank line betwen
 148                 rows in order to visually separate the entries. Better than the default
 149                 but certainly not great. The output of these macros is extreamely  space
 150                 sensitive (leading spaces because python programmers believe these
 151                 kinds of "everythign must align" parsers are good).
 152
 153                 It seems that not all HTML generated from RST is done consistently. As an example
 154                 the HTML generated for read the docs does NOT respect the no boarder option
 155                 on tables, and adds additional space at the bottom of each table.  Thus there
 156                 are two sets of definition list macros; by default the RTD style of ignoring
 157                 directives is assumed. The alternate set can be enabled by setting the variable
 158                 'sane_dlist' before imbedding this definition file.
 159
 160                 When sane_dlist is set to 1, definition list items will be separated with a row
 161                 separater applied at the start of rows 2-n.
 162
 163                 RST requires a blank line prior to the start of the list, so we force one.
 164         .fi
 165
 166         .** beg_dlist parms 1 and 2 are for PFM, $3 is for rst and is optionally the term,def widths (e.g. 15,80)
 167         .** mind the tildas (end of line escapes in {X}fm
 168         .**
 169         .if &{sane_dlist!0} 1 =
 170                 .dv beg_dlist   .dv di_term 1 ^: ~
 171                                                 .dv row_sep .sp 1 ^: ~
 172                                                 .sp 1 ~
 173                                                 .in +&_ch4 ~
 174                                                 ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0  .br ^:class^: borderless ~
 175                                                 .in +&ch_6
 176
 177                 .dv ditem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
 178                 .dv ditem_nosp  .in -&{_ch4} * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
 179
 180                 .dv di     ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
 181                 .dv diitem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
 182
 183         .ei
 184                 .dv beg_dlist   .dv di_term 1 ^: ~
 185                                                 .dv row_sep .sp 1 ^: ~
 186                                                 .sp 1 ~
 187                                                 .in +&_ch4 ~
 188                                                 ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0  .br ^:class^: borderless ~
 189                                                 .in +&ch_6
 190
 191                 .dv ditem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
 192                 .dv ditem_nosp ^&row_sep * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
 193                 .dv di  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
 194                 .dv diitem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
 195         .fi
 196
 197         .** auto numbering ditem has to be hacked in since we're completely unable to use {X}fm's list gen for RST
 198         .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 + ]
 199
 200         .dv end_dlist .sp 1 .in -&{_ch10} .sp 1
 201
 202         .** generate a table with borders
 203         .dv beg_table ^.. list-table^:^: .br ^`   ^` ^:widths^: $1 .br ^`   ^` ^:header-rows^: 0 .sp 1
 204
 205         .** generate a table without borders
 206         .dv beg_table_nb ^.. list-table^:^: .br ^`   ^` ^:widths^: $1 .br ^`   ^` ^:header-rows^: 0  .br ^`   ^` ^:class^: borderless .sp 1
 207
 208         .** remainder of table support commands not dependent on borders/borderless
 209         .dv col .in 0i .br ^` `   -` ^` .in 56p
 210         .dv row .in 0i .sp 1 ^` ` * -` ^` .in 56p
 211         .dv end_table .sp 1 .in 0i
 212         .dv tab_cell ^&col
 213         .dv tab_row ^&row
 214
 215         .ju off