Re: [Groff] Proposed revised START macro for mom

[Peter Schaffter]

Greetings.

<personal note>
I haven't had much time in the past few months to work on mom.  I've a
novel going into production in a couple of months, another one on the
go that's not getting the attention it deserves AND I'm in the middle
of leaving my beloved Québec for the dreaded Canadian province of
Ontario.  Once the dust settles (in about six weeks), I'll get back to
taking care of mom as she deserves. :)
</personal note>

On Tue, Jan 07, 2003, James J. Ramsey wrote:
> I created a modified version of the START macro in
> -mom that is more customizable than the original. The
> changes I made were pretty much a reshuffling of the
> code so that if the PRINTSTYLE was set to TYPESET, the
> following macros could be redefined to change the look
> of the docheader:
> 
> .TITLE_DOCHEADER \" Controls the docheader when the 
> .                \" DOCTYPE is set to DEFAULT
> 
> .CHAPTER_DOCHEADER \" Controls the docheader when the 
> .                  \" DOCTYPE is set to CHAPTER
> 
> .NAMED_DOCHEADER \" Controls the docheader when the 
> .                \" DOCTYPE is set to NAMED
> 
> The default definitions of the above macros print out
> docheaders that should be identical to the docheaders
> printed by the original.

On quick inspection, I'm not sure I see the end-user advantage of these
macros over the original definitions in START.  However, they clean up
the coding considerably, and that alone makes them worth the price of
admission.  After I've gone over the proposed changes thoroughly, I'll
most likely incorporate them into the next release of mom.
 
> The following macro is used inside TITLE_DOCHEADER and
> NAMED_DOCHEADER to make them easier to read:
> 
> .PRINT_AUTHORS \"Prints the arguments of the AUTHOR
> macro one to a line.
> 
> The PRINT_AUTHORS macro just contains the "while" loop
> that the original START macro used to print the
> arguments of AUTHOR. I just hid the loop inside a
> macro.
> 
> The following strings were defined and used in the
> *_DOCHEADER macros to make them easier to read:
> $TITLE_PT_SIZE, $SUBTITLE_PT_SIZE, $AUTHOR_PT_SIZE,
> and $DOCTYPE_PT_SIZE. Like the PRINT_AUTHORS macro,
> the defined strings just encapsulate code already
> present in the original START macro. By default, they
> are defined as
> 
> \\n[#DOC_PT_SIZE]u\\*[$TITLE_SIZE_CHANGE]
> \\n[#DOC_PT_SIZE]u\\*[$SUBTITLE_SIZE_CHANGE]
> \\n[#DOC_PT_SIZE]u\\*[$AUTHOR_SIZE_CHANGE]
> \\n[#DOC_PT_SIZE]u\\*[$DOCTYPE_SIZE_CHANGE]

Again, these definitely improve readability, hence I'll be happy to
incorporate them.
 
> I did add one macro that actually adds a feature to
> -mom, namely CHAPTER_TITLE. If you want a chapter
> heading like this,
> 
> Chapter 1
> My Favorite Widgets

Excellent idea.  I hadn't thought of it.  Thanks.

> you can pass the argument "My Favorite Widgets" to
> CHAPTER_TITLE. By default, "My Favorite Widgets" will
> be set in $SUBTITLE_FT.

In keeping with mom's way of doing things, I'll add the usual control
macros so end-users can modify the family, font, pointsize, etc of
CHAPTER_TITLE.

> Some concerns:
> 
> In the original code for typesetting the docheaders,
> the line \\n+[#DOCHEADER_LINES] occurs multiple times.
> In the revised macro, all those lines using the
> #DOCHEADER_LINES register were eliminated. So far as I
> can tell, that register was only used to fine-tune the
> space after the docheader, and the only telltale of
> its absence is a slightly smaller amount of space
> after the docheader on page 5 of the PostScript output
> of the revised typeset.mom. That said, there is a
> possibility that I may have introduced a bug by
> eliminating those lines.

#DOCHEADER_LINES is actually quite important, for the fine-tuning reason
you give above.  However, it's only by pure coincidence that their
absence on page 5 of typeset.mom when it's processed with your proposed
macros doesn't seem to have any significant effect.

Explanation
-----------
To quote the documentation: "Mom takes evenly-aligned bottom margins
in running text very seriously."  She does this by calculating the
spacing of all document elements based on integer multiples of the
leading used in normal paragraphs (#DOC_LEAD).  Since the docheader
typically uses a leading different from #DOC_LEAD, and that leading is
furthermore adjustable by the end-user, mom needs to know the precise
depth of the docheader in order to add a corrective amount of space from
the distance between the last line of the docheader and the first line
of running text.  With the correction, the first line of running text
always falls on a #DOC_LEAD baseline, which it has to do otherwise page
1 of a document risks running short (or long; sometimes, with groff,
it's hard to predict which).

The repeated (and therefore incrementing) #DOCHEADER_LINES register
keeps track of the number of lines in a docheader.  At the end of the
docheader, mom multiplies the number of docheader lines by the docheader
leading to establish the depth of the docheader.  She then compares this
depth with the depth the docheader would have had if the leading were
the same as that used in running text.  Once that's done, she adjusts
for the difference.

Therefore, the incrementing register #DOCHEADER_LINES needs to go back
into your macros.

> $TITLE_PT_SIZE and friends really should be number
> registers, not strings. However, when I attempted to
> make them registers (replacing \\* with \\n where
> appropriate, groff barfed. I'm not sure why.

Me, either.  However, regardless of groff's difficulties digesting
TITLE_PT_SIZE as a register, it still has to be a string because
$TITLE_SIZE_CHANGE (the second part of the definition of $TITLE_PT_SIZE)
holds a user-settable string that may include decimal fractions.
Registers can't hold decimal fractions (they get rounded off to
integers) -- a severe but understandable annoyance when writing complex
macros.
 
> So far as I can tell, strings like $TITLE_FAM,
> $TITLE_FT, $CHAPTER, etc. are really intended for
> internal use, yet they appear in the macros
> TITLE_DOCHEADER, CHAPTER_DOCHEADER, and
> NAMED_DOCHEADER, which are explicitly meant to be
> modified by -mom users.

You're right.  $TITLE_FAM, $TITLE_FT, etc are intended for internal
use.  That you've used them in macros like TITLE_DOCHEADER (which, BTW,
should probably be changed to DEFAULT_DOCHEADER for mom-consistency) is
a Good Thing.  Mom's mandate for document processing is to provide
end-users (especially newbies to groff) with maximum control over
document design without having to go into the macro file at all.
However, there's considerable latitude between "mandate" and reality,
as your macros "explicitly meant to be modified" demonstrate.  Hence,
it's a good idea to leave mom's internal strings in your macros; anyone
with the urge and the knowledge to modify om.tmac shouldn't have too
much difficulty changing them to absolute values or strings of their own
definition.

-- 
        +-----------------------------------------------------------+
        | "For-profit medical care is the Hippocratic equivalent of |
        |                   for-profit religion."                   |
        +-----------------------------------------------------------+
PTPi
Peter Schaffter
31, Curé-André-Préseault
Appt. 22
Gatineau (Québec)
CANADA  J8T 6E4

A confirmed GNU/Linuxer. Sorry, I don't do Windows.