[help-texinfo] Re: Dividing a texinfo document into parts?

[Brooks Moses]

Karl Berry wrote:
> Hi Brooks,

Hello!

>     I'm working on a 150-page texinfo manual, 
>
> Cool.  What's it for?

The GNU Fortran compiler front-end for GCC.  At this point, it's a 
pretty loosely-organized collection of things, and I'm trying to put it 
into a more useful order.

>     don't see anything obvious in the manual.
>
> Yeah, because something like @part has never been implemented :(.  (Been
> on the TODO list I-don't-know-how-many-years.)
>
> Adding another sectioning level, one that is optional, to makeinfo
> sounds like a pain.  My suggestion for info would be to write it out
> manually in the top-level menu (other manuals do this, e.g., Emacs).
>
> @menu
> * Intro::
>
> Part I: foo
> * chap1::
> ...
>
> Part II: bar
> * chap5
> @end menu

That looks like pretty much exactly what I'd want on the makeinfo side, 
anyway -- I hadn't realized you could put non-linked text in the menu 
(but, then, I suppose I hadn't looked at the manual for that part very 
closely).

> Implementing @part for TeX doesn't sound too hard, really.  But barring
> figuring out all the details now, I think you can manage an equivalent
> doing something like this (totally untested, and I'm sure I've got stuff
> wrong):
>
> @tex
> {\chapfonts
> Part I:@*
> This is my first part
> }
> \writetocentry{part}{This is my first part}{I}
> \page
> @end tex
>
> And, at the beginning:
> @tex
> \gdef\dopartentry#1#2#3#4{%
>   \tocentry{Part #3: #1}{#4}
> }
> @end tex

Looks like that needs to be \partentry rather than \dopartentry, and 
needs a little font tweaking, but mostly it works.  (There is a problem 
in PDF files, because the treatment of \pdfmakeoutline doesn't properly 
reset \partentry to something that doesn't produce output, and so we get 
extra "Part I:..." entries after the full TOC.  I did find a workaround, 
though, defining \partentry to call \unnchapentry when the full TOC is 
created.)

I do have one question about implementation.  I'd like to have the 
"part" lines and numbers in the short version of the contents be 
boldface but otherwise in textfont.  What I ended up with was the following:

\gdef\partentry#1#2#3#4{%
  \vskip .5\baselineskip plus.2\baselineskip
  \begingroup
    \let\rm=\bf \rm
    \tocentry{Part #2: #1}{\doshortpageno\bgroup#4\egroup}
  \endgroup
}

The \let\rm=\bf is a bit of an unpleasant hack.  It looks like to me, 
extrapolating from how the fonts are set in the \chapterfonts and so 
forth, that \let\tenrm=\textbf would be the right way to do this (or, 
probably, separating that all off into a \partentryfonts macro), but 
that doesn't actually change anything.  What am I missing?

> Now, if it's not totally urgent and we want to figure out what the best
> specification is, I'm open to that discussion.  I kind of imagine
> something like @titlepage:
>
> @partpage
> @parttitle This is my first part
> ... whatever else, regular Texinfo text ...
> @end partpage
>
> It would be ignored by makeinfo, as titlepage is.
>
> Wdyt?

That looks pretty reasonable, and I'd be happy with it, though if the 
"whatever else" is ignored by makeinfo I wouldn't want to put too much 
text there.

An alternate way of handling things would be to put the "Part" heading 
on the same page as the following chapter heading, with a syntax of:

  @part This is my first part

  @node A chapter
  @chapter A chapter
  ...

I think I'd have a slight preference for the latter, but I'm not sure 
how complicated it would be to set that up with relation to the chapter 
commands that handle the page breaks before the chapter.

I suppose one way to set that up would be to let @part act essentially 
as an unnumbered chapter, perhaps including the handling in makeinfo. 
That way, with a style where chapters don't get page breaks, the part 
heading would go inline in the text like a chapter heading, but in a 
style with page breaks, it would get its own page, along with any 
following text.  (And handling it like an unnumbered chapter in makeinfo 
means that there's a place for that following introductory text to go in 
the info version.)

Then again, I suppose one could just use \pchapsepmacro to do the 
skipping before and after the @partpage environment, and thus let it be 
an inline block instead of a page when chapters don't get page breaks. 
That's probably the simplest option, really, and it also handles putting 
things on odd pages if needed.

Thoughts?

- Brooks