Add route table guide and formatting tweaks
[ric-plt/lib/rmr.git] / doc / src / rst.im
index e5d74db..6082da2 100644 (file)
@@ -1,7 +1,7 @@
 .if false
 ==================================================================================
-       Copyright (c) 2019 Nokia
-       Copyright (c) 2018-2019 AT&T Intellectual Property.
+       Copyright (c) 2019-2020 Nokia
+       Copyright (c) 2018-2020 AT&T Intellectual Property.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
        .** convert {X}fm input into rts.
        .** post processing is needed to strip the leading space that tfm insists on adding.
 
-       .** bloody rst has no consistant marking character, and each header level must be different and as long as the text.
-       .** and of course they don't generate <hx> tags in the resulting HTML, but <section> tags. WTF?
+       .** character offsets needed to provide bloody indention significant crap.
+       .** tfm converts points to characters using 7p/ch so these guarentee correct
+       .** spacing.
+       .**
+       .dv _ch2 14p
+       .dv _ch4 28p
+       .dv _ch6 42p
+       .dv _ch8 56p
+       .dv _ch10 70p
+
+       .** Long strings of equals and dashes needed to make title/subtitle easier to generate. Multi
+       .** line annotations for headers could be used, but the code is messy for what results in
+       .** 4 lines in the setup files.
+       .**
        .dv many_equals ============================================================================================
        .dv many_dashes --------------------------------------------------------------------------------------------
        .dv many_tildas ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-       .dv h1 .sp 1 $1 .br &many_equals .sp 1
-       .dv h2 .sp 1 $1 .br &many_dashes .sp 1
-       .dv h3 .sp 1 $1 .br &many_tildas .sp 1
 
-       .** bloody rst won't allow breaks in a bullet list so we have to allow the column to go wide.
-       .dv cd 1 180i m=0i
+       .gv semver
+       .if &_major 1 >
+               .** tfm version 2.0.0+ supports header annotation for rst
+               .dh 1 a==after s=2,1 i=0 m=0
+               .dh 2 a=-after s=2,1 i=0 m=0
+               .dh 3 a=~after s=2,0 i=0 m=0
+
+               .dv h1 .h1 $1
+               .dv h2 .h2 $1
+               .dv h3 .h2 $1
+       .ei
+               .dv __alert ### WARNING ###  rst.im detects an old(er) version of tfm some formatting might not be right
+               .sv __alert
+
+               .dh 1 s=2,1 i=0 m=0
+               .dh 2 s=1.1 i=0 m=0
+               .dh 3 s=1,0 i=0 m=0
+
+               .dv h1 .sp 1 $1 .br &many_equals .sp 1
+               .dv h2 .sp 1 $1 .br &many_dashes .sp 1
+               .dv h3 .sp 1 $1 .br &many_tildas .sp 1
+       .fi
+
+       .dv cd 1 &{col_width!8.0i} m=0i
 
        .dv h4 **$1**
-       .** .dv h1 === $1 .br ===  .sp 1
-       .** .dv h2 === $1 .br === .sp 1
-       .** .dv h3 === $1 .br === .sp 1
 
-       .dv fig
+       .dv fig .fg $1
+       .dv fig_cen .fg $1
        .dv set_font_cw
 
        .dv nf  .sp 1 ^:^: .br .ll -2 .in +2
        .dv indent
        .dv uindent
 
-       .dv lic1 +
+       .** list item characters
+       .dv lic1 *
        .dv lic2 -
-       .dv lic3 *
+       .dv lic3 +
 
        .in 0i                                          .** bloody rst is indention sensitive like markdown; sheesh
 
-       .dv esc \ : .** bloody need to escape _ and * at the end of a word
+       .dv esc \$1 : .** bloody need to escape _ and * at the end of a word
        .dv line_len .ll $1
        .dv space .sp 1
        .dv half_space .sp 1
+       .dv break .br |
        .dv mult_space .sp $1
-       .dv beg_list .ll 17i .sp 1 .dv lic $1 ^:
-       .dv end_list .ll 6i .sp 1
 
-       .dv beg_dlist .sp 1  .ll -3
-       .dv end_dlist .br .in 0i .ll +3
+       .** ------- bullet lists -------------------------
+       .dv beg_list .sp 1 .bl ${1!*} ^: .br
+       .dv end_list .el .sp 1
+       .dv li .br .li
 
-       .** for now we allow only a single layer of defitems
-       .dv di     .in 0i .br  $1 .br .in +3
-       .dv ditem .in 0i .br  $1 .br .in +3
-       .** diitem is odd and deprecated
-       .dv diitem .in 0i .br  $1 .br .in +3
-       .dv item .br &lic
-       .dv li .br &lic
-
-       .dv ex_start .sp 1 ^:^: .br .ll -2 .in +2 .nf
+       .dv ex_start .sp 1 ^:^: .sp 1 .ll -2 .in +2 .nf
        .dv ex_end .fo on .in -2 .ll +2 .sp 1
+       .dv ex_end_fig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
+       .dv ex_end_cfig .fo on .in -2 .ll +2 .fg $1 ^: .sp 1
 
        .dv proto_start .sp 1 .cc .5i .st 9 .sf Courier-bold .nf
        .dv proto_end .fo on .sf ^&text_font .st ^&text_size .sp .3
 
        .dv center .br $1 .br
-       .dv center_start .br
-       .dv center_end .br
+       .dv center_start ^.. class:: center .br
+       .dv center_end .sp 1
 
        .** fonts and font macros
        .dv ital *$1*
        .dv bold **$1**
-       .dv cw $1
+       .dv cw ^^^`^^^`$1^^^`^^^`
+       .** global font changes seem impossible in RST
        .dv set_font_prop
 
-       .dv table .sp 1 ^[table not supported in rst output]  .if false
-       .dv tab_cell
-       .dv tab_row
-       .dv end_table .fi
-
        .dv super .sm ^[ .sm ^&{ss_num}]
        .dv ss_num 1
        .dv note .dv ss_num ^[ ?%.0f ^&ss_num 1 + ] ^: .sm ^^[^&{ss_num}]
        .** rst has no concept of a page, so all notes go to the close of the doc
        .dv atbot atclose
 
+
+       .** ----------- definition lists and tables ------------------------------------
+       .if false
+               A list table without borders should build a reasonable def list in
+               RST. What RST touts as a def list turns out looking like crap, so we
+               jump some hoops to generate a two column table.
+               The usual pratcice of adding half space between items is ignored
+               by rst, and we add addtional "logic" to insert a blank line betwen
+               rows in order to visually separate the entries. Better than the default
+               but certainly not great. The output of these macros is extreamely  space
+               sensitive (leading spaces because python programmers believe these
+               kinds of "everythign must align" parsers are good).
+
+               It seems that not all HTML generated from RST is done consistently. As an example
+               the HTML generated for read the docs does NOT respect the no boarder option
+               on tables, and adds additional space at the bottom of each table.  Thus there
+               are two sets of definition list macros; by default the RTD style of ignoring
+               directives is assumed. The alternate set can be enabled by setting the variable
+               'sane_dlist' before imbedding this definition file.
+
+               When sane_dlist is set to 1, definition list items will be separated with a row
+               separater applied at the start of rows 2-n.
+
+               RST requires a blank line prior to the start of the list, so we force one.
+       .fi
+
+       .** beg_dlist parms 1 and 2 are for PFM, $3 is for rst and is optionally the term,def widths (e.g. 15,80)
+       .** mind the tildas (end of line escapes in {X}fm
+       .**
+       .if &{sane_dlist!0} 1 =
+               .dv beg_dlist   .dv di_term 1 ^: ~
+                                               .dv row_sep .sp 1 ^: ~
+                                               .sp 1 ~
+                                               .in +&_ch4 ~
+                                               ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0  .br ^:class^: borderless ~
+                                               .in +&ch_6
+
+               .dv ditem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
+               .dv ditem_nosp  .in -&{_ch4} * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
+
+               .dv di     ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
+               .dv diitem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .sp 1 | .in -&{_ch4} .sp 1 ^:
+
+       .ei
+               .dv beg_dlist   .dv di_term 1 ^: ~
+                                               .dv row_sep .sp 1 ^: ~
+                                               .sp 1 ~
+                                               .in +&_ch4 ~
+                                               ^.. list-table^:^: .in +&_ch2 ^:widths^: ${3!auto} .br ^:header-rows^: 0  .br ^:class^: borderless ~
+                                               .in +&ch_6
+
+               .dv ditem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
+               .dv ditem_nosp ^&row_sep * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
+               .dv di  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
+               .dv diitem  ^&row_sep  * -  **$1** .in +&_ch2 - .in +&_ch2 .dv row_sep .in -&{_ch4} .sp 1 ^:
+       .fi
+
+       .** auto numbering ditem has to be hacked in since we're completely unable to use {X}fm's list gen for RST
+       .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 + ]
+
+       .dv end_dlist .sp 1 .in -&{_ch10} .sp 1
+
+       .** generate a table with borders
+       .dv beg_table ^.. list-table^:^: .br ^`   ^` ^:widths^: $1 .br ^`   ^` ^:header-rows^: 0 .sp 1
+
+       .** generate a table without borders
+       .dv beg_table_nb ^.. list-table^:^: .br ^`   ^` ^:widths^: $1 .br ^`   ^` ^:header-rows^: 0  .br ^`   ^` ^:class^: borderless .sp 1
+
+       .** remainder of table support commands not dependent on borders/borderless
+       .dv col .in 0i .br ^` `   -` ^` .in 56p
+       .dv row .in 0i .sp 1 ^` ` * -` ^` .in 56p
+       .dv end_table .sp 1 .in 0i
+       .dv tab_cell ^&col
+       .dv tab_row ^&row
+
        .ju off