X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Frst.im;fp=doc%2Fsrc%2Frst.im;h=6082da2a19133dcc8980d3f6b17866d362f07ee5;hb=a3a121ca4a0426ec964fa684fb27c397f2ee9e24;hp=e5d74dbc96cfe95b470733099d0fedade698104a;hpb=2b3c393e660c5e1037191f43cc70537da8316b89;p=ric-plt%2Flib%2Frmr.git 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 tags in the resulting HTML, but
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