Add route table guide and formatting tweaks
The route table guide has been added to the repo so that it
can be published on the RTD site. This change also includes
pulling full examples into the user guide from the repo
example directory (rather than maintaining snipits in the
doc), and generates RST definition lists in a more traditional
format that just look better in the rendered HTML.
Issue-ID: RIC-378
Signed-off-by: E. Scott Daniels <daniels@research.att.com>
Change-Id: I2661dbb28daf3575640426a847f17fe45ea0ba43
diff --git a/doc/src/rst.im b/doc/src/rst.im
index e5d74db..6082da2 100644
--- a/doc/src/rst.im
+++ b/doc/src/rst.im
@@ -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.
@@ -37,24 +37,53 @@
.** 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
@@ -63,56 +92,123 @@
.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