Re: [Forwarded] GPC 2.1 released

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

On Tue, 14 May 2002, Frank Heckenbach wrote:

> > * Using only Make-lang.in, no separate Makefile.in for the front end
> > directory.
> 
> I'm planning to do this soon, anyway. Is there anything to watch out
> for when doing it (I suppose you have some experience with other
> frontends in this regard)?

I think Zack did this for most front ends (Chill, now removed, wasn't
done; Ada hasn't yet been done, I think because of issues to do with still
supporting using the Ada front end with 2.8.1-based compilers).

> Certainly not for every paper size, but IMHO it should look alright
> for the standard size. BTW, I did not add these checks "arbitrarily

The trouble is, there isn't a "standard size".  Most of the world will use 
A4, but the USA won't.  Printed versions, distributed by the FSF, will 
probably use @smallbook.  (gcc/doc/include/gcc-common.text now has an 
FSFPRINT conditional that sets @smallbook.  This should also be used to 
control whether ISBNs are printed.)

> without good reason", but for the very concrete reason that some
> things (like long URLs and too long lines in example code) sometimes
> caused overfull boxes and didn't look good (to put it mildly) in the
> manual. Since we offer DVI, PS and PDF files on our website and
> might distribute printed copies in the future, I simply want to make
> sure they look right (without looking through the files myself each
> time).

I don't see any real alternatives to making such checks carefully when the
FSF want to print the manual (as well as generally e.g. keeping example
lines short, putting long URLs on display rather than in running text).  
If you set a paper size in the manual, overriding texinfo.cnf, you'll
cause problems for people who've set a local paper size for a reason.  If
you don't, but cause a hard error on overfull hboxes, you'll cause
problems for people who've set a size different from what the manual was
tested with.

> As for not silencing TeX, what's become of the good old Un*x
> principle that a command should be silent unless a problem occurs?
> ISTM that this principle is not valued much in GCC (e.g., building
> GCC produces some warnings that could probably be eliminated with
> some effort, and `configure --silent' seems to be broken since 2.95
> (*)), but I prefer it very much because this way I can do a complete
> GPC build (including documentation and some cross builds) without
> any output (except for the warnings in toplev.c), and when any new
> problems (e.g., warnings) appear, I see them directly without
> looking through a long output.

Building produces a huge amount of make bootstrap output with the 
compilation commands anyway.  contrib/warn_summary exists to analyse logs 
for warnings.

TeX is (like Emacs) not a traditional Unix command; it's an application
from some other operating system tradition that is now generally used on
Unix.  There's no clear definition of which output from it is useful to 
whom; sometimes underfull hbox warnings may be wanted, sometimes the list 
of files being read may cause one to notice the wrong file is being 
included or some file that should be included in the manual isn't.

> > actually setting the
> > paper size in the manual, except for FSFPRINT, is wrong),
> 
> OK, I'll do this via the command line (`-t') now. Is that the
> recommended way?

The recommended way is to leave it to the user - which they can do using 
texinfo.cnf, or by using -t when running texi2dvi manually - and not to 
set a specific paper size in the GCC distribution.

> If we can't agree in the other points, I think we could just just an
> environment variable or two different build rules (or a configure
> option, though I wouldn't know how to implement it) to support out
> different needs.

In general, try to make such features general - e.g., implement a 
configure option for all front ends.  (And support for HTML and PDF 
manuals - probably using lang.html and lang.pdf Make-lang.in hooks - 
should similarly be done in some consistent way across front ends.  
There's no support for it in GCC at present, and it would be a good thing 
to add.)

> > put the contents
> > list in the right place in the manual in the first place rather than
> > reordering the .dvi file,
> 
> Can I just move the `@summarycontents' and `@contents' after the
> `@end titlepage', or is there anything to watch out for? (Since
> gcc.texi until 2.95.x had them at the end, I wasn't sure if there
> are any issues, so I rather wrote the dvi-reorder kludge to avoid
> breaking anything else ...) Is a certain version of texinfo required
> for it to work?

Just put the contents commands in where you want them.  texi2dvi will
rerun TeX as many times as needed.  The minimum makeinfo version for GCC
is currently 4.1; certainly that version of texi2dvi, or indeed 4.0, will
work.  There were only problems with the old system of running tex;  
texindex; tex manually in the Makefile, rather than rerunning as much as
needed for page references to stabilise.

> I plan to do this soon, just didn't get around to this yet, since
> the first texinfo release with a usable `--html' (i.e. with file
> splitting) was not so long ago. (I'm personally not happy with
> texi2html at all, so I like to get rid of it ASAP.)

Indeed, 4.1 has various fixes for problems found when we replaced 
texi2html with makeinfo --html for building onlinedocs.  (texi2html had 
problems with some of the macros used in GCC's manuals; makeinfo --html 
avoided those by using the same parser as ordinary makeinfo, and provided 
persistent URLs for parts of the manual, but problems then showed up and 
needed to be fixed when we put it into production use.)

> > * See also the list in "Anatomy of a Language Front End" in
> > sourcebuild.texi, to ensure that when adding it you do add a complete
> > front end, with all the associated documentation etc. bits needed.
> 
> Is there a way to get this file without doing a complete CVS
> checkout?

All the current mainline manuals are on the GCC web site 
(http://gcc.gnu.org/onlinedocs/gccint/Front-End.html is the relevant 
node).  Or the file can be obtained from cvsweb.

-- 
Joseph S. Myers
jsm28@cam.ac.uk