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
  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.
  54         .**
  55         .dv many_equals ============================================================================================
  56         .dv many_dashes --------------------------------------------------------------------------------------------
  57         .dv many_tildas `^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`
  58
  59
  60         .gv semver
  61         .if &_major 1 >
  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
  66
  67                 .dv h1 .h1 $1
  68                 .dv h2 .h2 $1
  69                 .dv h3 .h2 $1
  70         .ei
  71                 .dv __alert ### WARNING ###  rst.im detects an old(er) version of tfm some formatting might not be right (&_major)
  72                 .sv __alert
  73
  74                 .dh 1 s=2,1 i=0 m=0
  75                 .dh 2 s=1.1 i=0 m=0
  76                 .dh 3 s=1,0 i=0 m=0
  77
  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
  81         .fi
  82
  83         .dv cd 1 &{col_width!8.0i} m=0i
  84
  85         .dv h4 **$1**
  86
  87         .dv fig .fg $1
  88         .dv fig_cen .fg $1
  89         .dv set_font_cw
  90
  91         .dv nf  .sp 1 ^:^: .br .ll -2 .in +2
  92         .dv fo  .in -2 .ll +2 .sp 1
  93
  94         .dv indent
  95         .dv uindent
  96
  97         .** list item characters
  98         .dv lic1 *
  99         .dv lic2 -
 100         .dv lic3 +
 101
 102         .in 0i                                          .** bloody rst is indention sensitive like markdown; sheesh
 103
 104         .dv esc \$1 : .** bloody need to escape _ and * at the end of a word
 105         .dv line_len .ll $1
 106         .dv space .sp 1
 107         .dv half_space .sp 1
 108         .dv break .br |
 109         .dv mult_space .sp $1
 110
 111         .** ------- bullet lists -------------------------
 112         .dv beg_list .sp 1 .bl ${1!*} ^: .br
 113         .dv end_list .el .sp 1
 114         .dv li .br .li
 115         .dv item .br .li
 116
 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
 121
 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
 124
 125         .dv center .br $1 .br
 126         .dv center_start ^.. class:: center .br
 127         .dv center_end .sp 1
 128
 129         .** fonts and font macros
 130         .dv ital *$1*
 131         .dv bold **$1**
 132         .dv cw ^^^`^^^`$1^^^`^^^`
 133         .** global font changes seem impossible in RST
 134         .dv set_font_prop
 135
 136         .dv super .sm ^[ .sm ^&{ss_num}]
 137         .dv ss_num 1
 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
 140         .dv atbot atclose
 141
 142
 143         .** ----------- definition lists and tables ------------------------------------
 144         .if false
 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).
 154
 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.
 161
 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.
 164
 165                 RST requires a blank line prior to the start of the list, so we force one.
 166         .fi
 167
 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
 170         .**
 171         .if &{sane_dlist!0} 1 =
 172                 .dv beg_dlist   .dv di_term 1 ^: ~
 173                                                 .dv row_sep .sp 1 ^: ~
 174                                                 .sp 1 ~
 175                                                 .in +&_ch4 ~
 176                                                 ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0  .br ^:class^: borderless ~
 177                                                 .in +&ch_6
 178
 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 ^:
 181
 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 ^:
 184
 185         .ei
 186                 .dv beg_dlist   .dv di_term 1 ^: ~
 187                                                 .dv row_sep .sp 1 ^: ~
 188                                                 .sp 1 ~
 189                                                 .in +&_ch4 ~
 190                                                 ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0  .br ^:class^: borderless ~
 191                                                 .in +&ch_6
 192
 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 ^:
 197         .fi
 198
 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 + ]
 201
 202         .dv end_dlist .sp 1 .in -&{_ch10} .sp 1
 203
 204         .** generate a table with borders
 205         .dv beg_table ^.. list-table^:^: .br ^`   ^` ^:widths^: $1 .br ^`   ^` ^:header-rows^: 0 .sp 1
 206
 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
 209
 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
 214         .dv tab_cell ^&col
 215         .dv tab_row ^&row
 216
 217         .ju off