Tiny changes on commenting for PostScript text, plus doc update (#4250)

* Marginally improve comments

The PostScript text typesetting is black magic and too hard to penetrate for me now.  I added some more commets but this is not easy to understand, being all in reverse Polish notation to boot.  For now we will simply document that the paragraph mode does not support composite characters.

* Update text_common.rst_

Author: PaulWessel

doc/rst/source/text_common.rst_

@@ -148,7 +148,7 @@ Optional Arguments
 **-M**
     Paragraph mode. Files must be multiple segment files. Segments are
     separated by a special record whose first character must be *flag*
-    [Default is **>**]. Starting in the 3rd column, we expect to find
+    [Default is **>**]. Starting in the 3rd field, we expect to find
     information pertaining to the typesetting of a text paragraph (the
     remaining lines until next segment header). The information expected
     is (*x y* [*font angle justify*] *linespace parwidth parjust*),
@@ -159,8 +159,9 @@ Optional Arguments
     which may be **l**\ (eft), **c**\ (enter), **r**\ (ight), or
     **j**\ (ustified). The segment header is followed by one or more
     lines with paragraph text. Text may contain the escape sequences
-    discussed above. Separate paragraphs with a blank line.  Note that
-    here, the justification set via **-F+j** applies to the box alignment
+    discussed above, although composite characters are not supported.
+    Separate paragraphs with a blank line.  Note that here,
+    the justification set via **-F+j** applies to the box alignment
     since the text justification is set by *parjust*.
 
 .. _-N:

src/PSL_label.ps

@@ -31,7 +31,7 @@ static char *PSL_label_str =
 "%-	out where labels are placed and setting clip paths etc.\n"
 "%-\n"
 "%- NOTE: No longer used as replaced by static string in PSL_strings.h.\n"
-"%- 	 We keep the file in the repository as it may be simpler to see\n"
+"%- 	 We keep the file in the repository as it may be simpler to see and edit\n"
 "%-	 the logic in this file than in the static string.\n"
 "%-----------------------------------------------------------------------------\n"
 "\n"
@@ -672,33 +672,34 @@ static char *PSL_label_str =
 static char *PSL_text_str =
 "%-----------------------------------------------------------------------------\n"
 "%-	P. Wessel, version 1\n"
-"%-	Text justification for paragraphs.\n"
-"%-	Kept as separate file until stable.\n"
+"%-	Text justification for paragraphs. Invented via PostScript docs a long time ago.\n"
+"%-	Kept as separate file because it is easier to edit and see the logic here.\n"
 "%-	Knows about flush l,c,r and justified.\n"
-"%-	Knows about all GMT @ escapes, composites,\n"
+"%-	Knows about all GMT @ escapes, composites (but not in paragraph mode)\n"
 "%-	and underlining. No hyphenation.  1 page only.\n"
-"%- NOTE: No longer used as replaced by static string in PSL_strings.h.\n"
-"%- 	 We keep the file in the repository as it may be simpler to see\n"
+"%- NOTE: No longer used as is, as replaced by static string in PSL_strings.h.\n"
+"%- 	 We keep the file in the repository as it may be simpler to edit and see\n"
 "%-	 the logic in this file than in the static string.\n"
 "%-----------------------------------------------------------------------------\n"
 "\n"
-"/PSL_setfont {	% Set Font, size, and color if needed\n"
+"/PSL_setfont {	% Set Font, size, and color (if needed)\n"
+"  % Expects two arguments: Word flag and word index\n"
 "  /f exch def % Gets word flag from stack\n"
 "  /k1 exch def % Gets word index from stack\n"
 "  /fz PSL_size k1 get def	% Get font size\n"
-"  /fn PSL_fnt k1 get def	% Get font\n"
-"  fn PSL_lastfn eq fz PSL_lastfz eq and not {\n"
+"  /fn PSL_fnt k1 get def	% Get font number\n"
+"  fn PSL_lastfn eq fz PSL_lastfz eq and not { % If fonts or sizes differ we must update\n"
 "    fz PSL_fontname fn get Y	% Set font and size\n"
 "    /PSL_lastfn fn def\n"
 "    /PSL_lastfz fz def\n"
 "  } if\n"
-"  /fc PSL_color k1 get def\n"
-"  fc PSL_lastfc ne {\n"
+"  /fc PSL_color k1 get def  % Get color\n"
+"  fc PSL_lastfc ne {  % Not the same, must update color\n"
 "    /PSL_c fc 3 mul def\n"
 "    0 1 2 {PSL_c add PSL_rgb exch get} for C	% Get and set color\n"
 "    /PSL_lastfc fc def\n"
 "  } if\n"
-"  f 32 and 32 eq { % Underline\n"
+"  f 32 and 32 eq { % Turn underline on before plotting text\n"
 "    /PSL_UL fz 0.075 mul def\n"
 "    fz 0.025 mul W\n"
 "    /PSL_show {PSL_ushow} def\n"
@@ -709,24 +710,25 @@ static char *PSL_text_str =
 "}!\n"
 "\n"
 "/PSL_setfont2 {	% Only set font and size\n"
+"  % Expects two arguments: Word flag and word index\n"
 "  /f exch def % Gets word flag from stack\n"
 "  /k1 exch def % Gets word index from stack\n"
 "  /fz PSL_size k1 get def	% Get font size\n"
-"  /fn PSL_fnt k1 get def	% Get font\n"
+"  /fn PSL_fnt k1 get def	% Get font number\n"
 "  fn PSL_lastfn eq fz PSL_lastfz eq and not {\n"
 "    fz PSL_fontname fn get Y	% Set font and size\n"
 "    /PSL_lastfn fn def\n"
 "    /PSL_lastfz fz def\n"
 "  } if\n"
 "}!\n"
 "\n"
-"/PSL_wordheight {	% Gets word from stack, and calculates any adjustment to box height\n"
+"/PSL_wordheight {	% Gets word from stack, then calculates any adjustment to box height\n"
 "  0 0 M false charpath flattenpath pathbbox /up exch def pop /down exch def pop newpath\n"
 "  down PSL_ymin lt {/PSL_ymin down def} if\n"
 "  up PSL_ymax gt {/PSL_ymax up def} if\n"
 "}!\n"
 "\n"
-"/PSL_ushow {\n"
+"/PSL_ushow {  % Related to underline showing text\n"
 "  currentpoint /y0 exch def /x0 exch def\n"
 "  ashow\n"
 "  currentpoint pop /x1 exch def\n"
@@ -737,24 +739,25 @@ static char *PSL_text_str =
 "% Set font, size, and color.  Adjust baseline if needed. Place space and word\n"
 "\n"
 "/PSL_placeword {\n"
-"  /k exch def % Gets word index from stack\n"
+"  % Expects one argument: the word index from stack\n"
+"  /k exch def % Gets word index\n"
 "  /flag PSL_flag k get def\n"
 "  k flag PSL_setfont\n"
 "  /sshow {ashow} def\n"
-"  PSL_col 0 eq {		% First word on a line\n"
+"  PSL_col 0 eq {		% First word on a new line\n"
 "    /PSL_t 0 def			% 0 spaces before this word\n"
-"    flag 4 and 4 eq {	% Must skip one TAB\n"
+"    flag 4 and 4 eq {	% Flag says we must skip one TAB (here 4 spaces)\n"
 "      pr_char 0 (    ) ashow\n"
 "    } if\n"
 "  }\n"
-"  {				% Need to find spaces before this word\n"
-"    /f PSL_flag k 1 sub get def	% f is flag for previous word\n"
+"  { % Need to find spaces before this word\n"
+"    /f PSL_flag k 1 sub get def	% f is the flag for previous word\n"
 "    /PSL_t f 3 and def		% PSL_t is index into PSL_spaces and PSL_spacewidths for previous word\n"
 "    f 32 and 32 eq flag 32 and 32 eq and {/sshow {PSL_ushow} def} if\n"
 "  } ifelse\n"
 "  /thisword_bshift PSL_bshift k get def	% The baseline shift\n"
 "  thisword_bshift 0.0 ne {0 thisword_bshift G} if	% Shift baseline\n"
-"  flag 8 and 8 eq {	% First composite char\n"
+"  flag 8 and 8 eq {	% First composite char (flagged with 8)\n"
 "    pr_char 0 PSL_spaces PSL_t get sshow\n"
 "    k PSL_composite\n"
 "  } if\n"
@@ -766,18 +769,19 @@ static char *PSL_text_str =
 "}!\n"
 "\n"
 "/PSL_composite {	% Place a composite character\n"
+"  % Expects a word index from the stack\n"
 "  /k1 exch def % Get word index from stack\n"
-"  /k2 k1 1 add def\n"
-"  /char1 PSL_word k1 get def\n"
-"  /char2 PSL_word k2 get def\n"
-"  /flag2 PSL_flag k2 get def\n"
-"  /w1 char1 stringwidth pop def\n"
-"  flag2 64 and 64 eq {  % We have a font change before the 2nd composite character\n"
+"  /k2 k1 1 add def  % Index to the 2nd composite character\n"
+"  /char1 PSL_word k1 get def  % First character\n"
+"  /char2 PSL_word k2 get def  % Second character\n"
+"  /flag2 PSL_flag k2 get def  % Second character flag\n"
+"  /w1 char1 stringwidth pop def % Width of first character\n"
+"  flag2 64 and 64 eq {  % Here, 64 means we have a font change before the 2nd composite character\n"
 "    /fn2 PSL_fnt k2 get def  % Get the other font array number\n"
 "    fz PSL_fontname fn2 get Y  % Set font and size for the 2nd composite character\n"
 "  } if\n"
-"  /w2 char2 stringwidth pop def\n"
-"  /delta w1 w2 sub 2 div PSL_scale mul def\n"
+"  /w2 char2 stringwidth pop def % Width of second character\n"
+"  /delta w1 w2 sub 2 div PSL_scale mul def  % Adjust and center based on w1, w2\n"
 "  delta 0.0 gt {\n"
 "    /dx1 0 def\n"
 "    /dx2 delta def\n"
@@ -787,7 +791,7 @@ static char *PSL_text_str =
 "    /dx2 0 def\n"
 "  } ifelse\n"
 "  dx1 0 G currentpoint\n"
-"  flag2 64 and 64 eq {  % Must switch back to 1st composite character font and set it\n"
+"  flag2 64 and 64 eq {  % Must switch back to first composite character font and set it\n"
 "   /fn1 PSL_fnt k1 get def  % Get initial font\n"
 "    fz PSL_fontname fn1 get Y  % Set font and size\n"
 "  } if\n"
@@ -815,7 +819,7 @@ static char *PSL_text_str =
 "  /PSL_col 0 def\n"
 "}!\n"
 "\n"
-"% Calculate text paragraph height:\n"
+"% Calculate text paragraph height or place it:\n"
 "\n"
 "/PSL_textjustifier {\n"
 "  /PSL_mode exch def	% From stack. 0 -> calculate height, no text is placed, 1 -> place text\n"
@@ -836,14 +840,14 @@ static char *PSL_text_str =
 "  /line 0 def\n"
 "  /ncomp 0 def\n"
 "  /comp_width 0 def\n"
-"  0 1 PSL_n1 {		% Loop over all the words\n"
+"  0 1 PSL_n1 {		% Loop over all the words in the array\n"
 "    /i exch def		% The current loop index\n"
-"    /thisflag PSL_flag i get def					% # of space chars to follow this word\n"
-"    i 0 eq {\n"
+"    /thisflag PSL_flag i get def	% Number of space chars to follow this word\n"
+"    i 0 eq {  % At the first word\n"
 "      /PSL_t 0 def\n"
 "      /lastflag 0 def\n"
 "    }\n"
-"    { /lastflag PSL_flag i 1 sub get def\n"
+"    { /lastflag PSL_flag i 1 sub get def  % Can get the previous flag\n"
 "      /PSL_t lastflag 3 and def\n"
 "    } ifelse\n"
 "    % PSL_t is index into PSL_spaces and PSL_spacewidths\n"
@@ -877,9 +881,9 @@ static char *PSL_text_str =
 "    }\n"
 "    { % Must process current line and move to next\n"
 "      1 PSL_mode eq {		% Write out the first word on this line\n"
-"	% Determine how much to expand text and also justify left/center/right\n"
+"        % Determine how much to expand text and also justify left/center/right\n"
 "        start PSL_expand\n"
-"	start PSL_placeword\n"
+"        start PSL_placeword\n"
 "      }\n"
 "      {PSL_word start get PSL_wordheight\n"
 "      } ifelse\n"
@@ -932,7 +936,7 @@ static char *PSL_text_str =
 static char *PSL_prologue_str =
 "%-----------------------------------------------------------------------------\n"
 "%- NOTE: No longer used as replaced by static string in PSL_strings.h.\n"
-"%- 	 We keep the file in the repository as it may be simpler to see\n"
+"%- 	 We keep the file in the repository as it may be simpler to see and edit\n"
 "%-	 the logic in this file than in the static string.\n"
 "%-----------------------------------------------------------------------------\n"
 "% Begin pslib header\n"