doc/src/rst.im - oransc/ric-plt/lib/rmr - Gitiles

 .if false
 ==================================================================================
 	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.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
 ==================================================================================
 .fi

 .if false
 	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
 				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.

 	.** 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 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

 	.** list item characters
 	.dv lic1 *
 	.dv lic2 -
 	.dv lic3 +

 	.in 0i						.** bloody rst is indention sensitive like markdown; sheesh

 	.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

 	.** ------- 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 ^.. class:: center .br
 	.dv center_end .sp 1

 	.** fonts and font macros
 	.dv ital *$1*
 	.dv bold **$1**
 	.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
	.if false
	==================================================================================
	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.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	==================================================================================
	.fi

	.if false
	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
	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.

	.** 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 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

	.** list item characters
	.dv lic1 *
	.dv lic2 -
	.dv lic3 +

	.in 0i .** bloody rst is indention sensitive like markdown; sheesh

	.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

	.** ------- 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 ^.. class:: center .br
	.dv center_end .sp 1

	.** fonts and font macros
	.dv ital $1
	.dv bold $1
	.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