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
 114         .dv ex_start .sp 1 ^:^: .sp 1 .ll -2 .in +2 .nf
 115         .dv ex_end .fo on .in -2 .ll +2 .sp 1
 116         .dv ex_end_fig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
 117         .dv ex_end_cfig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
 118
 119         .dv proto_start .sp 1 .cc .5i .st 9 .sf Courier-bold .nf
 120         .dv proto_end .fo on .sf ^&text_font .st ^&text_size .sp .3
 121
 122         .dv center .br $1 .br
 123         .dv center_start ^.. class:: center .br
 124         .dv center_end .sp 1
 125
 126         .** fonts and font macros
 127         .dv ital *$1*
 128         .dv bold **$1**
 129         .dv cw ^^^`^^^`$1^^^`^^^`
 130         .** global font changes seem impossible in RST
 131         .dv set_font_prop
 132
 133         .dv super .sm ^[ .sm ^&{ss_num}]
 134         .dv ss_num 1
 135         .dv note .dv ss_num ^[ ?%.0f ^&ss_num 1 + ] ^: .sm ^^[^&{ss_num}]
 136         .** rst has no concept of a page, so all notes go to the close of the doc
 137         .dv atbot atclose
 138
 139
 140         .** ----------- definition lists and tables ------------------------------------
 141         .if false
 142                 A list table without borders should build a reasonable def list in
 143                 RST. What RST touts as a def list turns out looking like crap, so we
 144                 jump some hoops to generate a two column table.
 145                 The usual pratcice of adding half space between items is ignored
 146                 by rst, and we add addtional "logic" to insert a blank line betwen
 147                 rows in order to visually separate the entries. Better than the default
 148                 but certainly not great. The output of these macros is extreamely  space
 149                 sensitive (leading spaces because python programmers believe these
 150                 kinds of "everythign must align" parsers are good).
 151
 152                 It seems that not all HTML generated from RST is done consistently. As an example
 153                 the HTML generated for read the docs does NOT respect the no boarder option
 154                 on tables, and adds additional space at the bottom of each table.  Thus there
 155                 are two sets of definition list macros; by default the RTD style of ignoring
 156                 directives is assumed. The alternate set can be enabled by setting the variable
 157                 'sane_dlist' before imbedding this definition file.
 158
 159                 When sane_dlist is set to 1, definition list items will be separated with a row
 160                 separater applied at the start of rows 2-n.
 161
 162                 RST requires a blank line prior to the start of the list, so we force one.
 163         .fi
 164
 165         .** beg_dlist parms 1 and 2 are for PFM, $3 is for rst and is optionally the term,def widths (e.g. 15,80)
 166         .** mind the tildas (end of line escapes in {X}fm
 167         .**
 168         .if &{sane_dlist!0} 1 =
 169                 .dv beg_dlist   .dv di_term 1 ^: ~
 170                                                 .dv row_sep .sp 1 ^: ~
 171                                                 .sp 1 ~
 172                                                 .in +&_ch4 ~
 173                                                 ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0  .br ^:class^: borderless ~
 174                                                 .in +&ch_6
 175
 176                 .dv ditem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
 177                 .dv ditem_nosp  .in -&{_ch4} * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
 178
 179                 .dv di     ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
 180                 .dv diitem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
 181
 182         .ei
 183                 .dv beg_dlist   .dv di_term 1 ^: ~
 184                                                 .dv row_sep .sp 1 ^: ~
 185                                                 .sp 1 ~
 186                                                 .in +&_ch4 ~
 187                                                 ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0  .br ^:class^: borderless ~
 188                                                 .in +&ch_6
 189
 190                 .dv ditem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
 191                 .dv ditem_nosp ^&row_sep * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
 192                 .dv di  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
 193                 .dv diitem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
 194         .fi
 195
 196         .** auto numbering ditem has to be hacked in since we're completely unable to use {X}fm's list gen for RST
 197         .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 + ]
 198
 199         .dv end_dlist .sp 1 .in -&{_ch10} .sp 1
 200
 201         .** generate a table with borders
 202         .dv beg_table ^.. list-table^:^: .br ^`   ^` ^:widths^: $1 .br ^`   ^` ^:header-rows^: 0 .sp 1
 203
 204         .** generate a table without borders
 205         .dv beg_table_nb ^.. list-table^:^: .br ^`   ^` ^:widths^: $1 .br ^`   ^` ^:header-rows^: 0  .br ^`   ^` ^:class^: borderless .sp 1
 206
 207         .** remainder of table support commands not dependent on borders/borderless
 208         .dv col .in 0i .br ^` `   -` ^` .in 56p
 209         .dv row .in 0i .sp 1 ^` ` * -` ^` .in 56p
 210         .dv end_table .sp 1 .in 0i
 211         .dv tab_cell ^&col
 212         .dv tab_row ^&row
 213
 214         .ju off