.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.
Mnemonic: rts.im
Abstract: This file provides macros allowing {X}fm source to generate
rts input from {X}fm source when the doc is passed through
- tfm, and to generate postscirpt output when passed through
+ tfm, and to generate postscirpt output when passed through
pfm. Simalar to the roff.im macro set that allows the generation
of troff input for man pages.
Author: E. Scott Daniels
Date: 7 February 2019
-
+
Maybe useful (but doesn't explain why real formatters aren't being used)
http://docutils.sourceforge.net/docs/user/rst/quickref.html
.fi
.** 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?
- .dv h1 .sp 1 $1 .br ============================================================================================ .sp 1
- .dv h2 .sp 1 $1 .br -------------------------------------------------------------------------------------------- .sp 1
- .dv h3 .sp 1 $1 .br ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .sp 1
+
+ .** 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. CAUTION: tildas must be quoted with back-ticks.
+ .**
+ .dv many_equals ============================================================================================
+ .dv many_dashes --------------------------------------------------------------------------------------------
+ .dv many_tildas `^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`
+
+
+ .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 (&_major)
+ .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 set_font_cw
-
+
+ .dv fig .fg $1
+ .dv fig_cen .fg $1
+ .dv set_font_cw
+
.dv nf .sp 1 ^:^: .br .ll -2 .in +2
.dv fo .in -2 .ll +2 .sp 1
.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 space .sp 1
.dv half_space .sp 1
+ .dv break .br |
.dv mult_space .sp $1
- .dv beg_list .sp 1 .dv lic $1 ^:
- .dv end_list .sp 1
-
- .dv beg_dlist .sp 1 .ll -3
- .dv end_dlist .br .in 0i .ll +3
-
- .** 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
+
+ .** ------- bullet lists -------------------------
+ .dv beg_list .sp 1 .bl ${1!*} ^: .br
+ .dv end_list .el .sp 1
+ .dv li .br .li
+ .dv item .br .li
+
+ .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 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 cw ^^^`^^^`$1^^^`^^^`
+ .** global font changes seem impossible in RST
+ .dv set_font_prop
.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