Re: using @titlepage in every format

[Gavin Smith]

On Wed, Feb 27, 2019 at 11:28:33PM +0100, Patrice Dumas wrote:
> > > Actually, in my experiments, the titlepage formatted like that looks
> > > pretty good in HTML, in an old-fashionned way, and somehow similar to 
> > > the TeX counterpart.
> > 
> > Can you send an example output file?  It not the default at the
> > moment and may not be what the users expect.  I doubt that we should
> > be imitating the style of the printed page in an electronic format
> > such as HTML.
> 
> An example:
> 
> http://zsh.sourceforge.net/Doc/Release/
> 
> It was the default for texi2html and in my opinion it looked better than
> the manuals produced by makeinfo which have nothing of the like.
> 
> > > I think that it would be better to have only one @titlepage for every
> > > format, which would not prevent from using @if* in it.  It does not
> > > prevent from using something like @documentinfo and @insertdocumentinfo
> > > or something like that to be able to set independently the meta data and
> > > format the @titlepage, but to me that's a different issue.
> > 
> > @titlepage could be an optional command to allow laying out the first 
> > couple of pages for printed output.  If @titlepage is not given but 
> > @documentinfo (or whatever it is called) is, this could be generated 
> > automatically without the @sp, @vskip etc. appearing in the Texinfo 
> > source.
> 
> It seems to me that in general, even an explicit formatting with @sp and
> @vskip would be ok in different formats.  Of course it won't be exactly
> the same, for instance @vskip is ignored in genearl, while @sp can be 
> rendered in most formats.  But still, it seems to me that in the default
> case the same formatting could be used.  Of course, if the manual
> authors are not satisfied with the result, they could tweak the results
> for the different formats with conditionals, but nevertheless, it seems
> to me that using the same @titlepage with the same formatting in every
> format is the best default.

I still think a different command from @titlepage should be used.  That 
would give the chance to get rid of layout commands like @sp in the 
source of manuals.  Inserting the contents of @titlepage automatically 
into the Top node in Info and HTML could have bad results for some 
existing manuals.

Maybe the <bookinfo> element of DocBook could be imitated and @bookinfo 
could be the name of this new command.  If there is some precedent for 
this in LaTeX, that could also give some ideas (I didn't find any in the 
time I spent on it.)  Other ideas: @manualinfo, @documentinfo.

> > However, I don't know where information about the publisher, ISBN 
> > numbers and cover art credits should go in the Texinfo document.  Maybe 
> > if somebody actually was printing a proper book they would use 
> > @titlepage after all.
> 
> To me keeping @titlepage, but using it in the default case in all the
> formats benefitting from a title page, which includes in my opinion html
> and Info would be the best.  The conditionals could still be used to do
> things differently based on the output, typically the ISBN numbers and
> cover art credits could be in @iftex @iflatex conditionals.

New commands could be invented to store the ISBN and other information, 
or maybe there could be a command @titleverso to store this 
miscellaneous information.  @titleverso might be thought to be the 
entire verso side of the title page, so maybe @titleversoextra.  Or 
maybe @titleverso could specify the entire page and provide a default 
version

@titleverso
@vskip 0pt plus 1filll
@insertcopying
@sp 1
@end titleverso

I thought of using @colophon or maybe @imprint, but these words seem not 
to have a very exact meaning.

Texinfo's own manual would undergo the following change:

--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -80,17 +80,16 @@ developing GNU and promoting software freedom.''
 @set txiindexhyphenignore
 
 
address@hidden
address@hidden
 @title Texinfo
 @subtitle The GNU Documentation Format
 @subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
 
 @author Robert J. Chassell
 @author Richard M. Stallman
address@hidden documentinfo
 
address@hidden Include the Distribution inside the titlepage so
address@hidden that headings are turned off.
-
address@hidden
address@hidden
 @vskip 0pt plus 1filll
 @insertcopying
@@ -107,7 +105,7 @@ ISBN 1-882114-67-1 @c for version 4.0, September 1999.
 
 @sp 1
 Cover art by Etienne Suvasa.
address@hidden titlepage
address@hidden titleverso
 
 
 @summarycontents

So @documentinfo would be a purely "semantic" command and @titleverso 
would keep some of the explict layout.

That would provide a basic output that is okay for PDF output, and allows 
us not to worry too much about the requirements of paper publishing, as 
it is overrideable anyway.

I think I am opposed to inserting the copying information automatically 
in the Top node.  There is considerable friction involved in accessing 
printed documentation - one has to buy the book, get it off the 
bookshelf, turn to the right page, and so on - in this case, leafing 
past the copyright page is not so much of an annoyance.  In the case of 
online documentation, it is quite different: one can load the manual 
very quickly.  Then looking at irrelevant information, like a copyright 
statement, is more of an annoyance.  People want to get to the 
information they need quickly.  I think a brief statement about 
what the manual is about is the best choice for a Top node.

So I doubt that any of the information from @titlepage should be output 
automatically in the @top node.