Re: more consistent ignoring before node and sections and Top node

[Patrice Dumas]

On Sun, Feb 20, 2022 at 10:42:25AM +0000, Gavin Smith wrote:
> On Sat, Feb 19, 2022 at 11:28:43PM +0100, Patrice Dumas wrote:
> > Hello,
> > 
> > Right now there is a diversity of handling of text at the beginning of
> > Texinfo manuals, before the first @node and sectioning, but also for the
> > informations in @titlepage that are not truly title page (@insertcopying
> > + publishing info), and also for the Top node.  It is this way to cope
> > both with printed output and for node based formats such as Info.  But
> > this is not done consistently for the different formats based on their
> > book/non book nature, and also it would be good to be able to have
> > book-like outputs for Plaintext and for HTML, in particular for epub.
> 
> The main issue is what is done with the Top node.  This serves the same
> function as a title page and table of contents for Info mode.  It's not
> necessary in many other output formats.

That is one issue, the other is the inconsistent handling of text before
node and sectioning commands, but you give your advice just below.

> There are also other commands that may occur at the start of a Texinfo
> file (@defcodeindex and so on), and these should be processed the same
> for all output formats.

Indeed, my proposal does not change that, the point is about what is
output, everything should be processed.

> Text before the first node is not a very important issue, but I think it
> should carry on being output as it is now.  I find this useful for testing
> texi2any, for example, in being able to write very short test files without
> writing so much "boilerplate".

Ok.  I would have preferred a more clear cut rule, and also avoided
anything before the content for a non book output, but it is not so
important and can be changed later.

> > For plaintext, I propose to have two options
> > * book-like: format the text before the first @node or sectioning
> >   command, not necessarily the @titlepage, but at least determine
> >   some title.  Do not output the Top node.
> > * non book: do not output the text before the first @node or
> >   sectioning command. If there is @*content before the first @node or
> >   sectioning command, the table of content is is still output
> >   before the first node or sectioning command.  The change is that
> >   text before the first @node or sectioning command is not output.
> > Default is non book.
> 
> It doesn't matter very much as nobody uses plaintext output anyway.  I
> think if these changes were made, there should be a more descriptive
> name for the option than "book-like".

Indeed, that's what I came to, but this is not for documentation, but for
comments.

> > DocBook is book-like, but does not allow any text outside of semantic
> > elements.  Text can be in abstract, dedication, preface, chapter but not
> > directly in <book>.  Title information and @copying are already used to
> > format the beginning of DocBook output.  I propose to ignore text before
> > the first @node or sectioning (unless there is a semantic markup), and
> > also not to output the Top node, both being changes.
> 
> Ignoring "pre-nodal" paragraph content would be a fine change to make
> for DocBook; as you say, there is not a natural place for it.  I'm not
> sure what you mean by semantic markup but I don't think the presence of
> tags like @emph, @code etc. should make a difference.

What I meant by 'semantic markup' is that if we add, in the future, some
Texinfo markup more in line with DocBook semantic markup, we could use
more, but only if there are such additions to Texinfo.

> Ignoring Top node: only danger here is if people were using the output
> of DocBook to create HTML and relying on the Top node there as being
> a table of contents.  

This can't really be used that way, there is no @menu, nor a way to
put contents there.

> I expect it would be fine, though, as DocBook
> tools would probably supply their own table of contents.

Indeed, I tested both
 xsltproc -o ... /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl 
texinfo.xml
and 
 dblatex texinfo.xml

Both output the legalnotice based on @copying and create a table of
contents.  As a result there is a duplication of content of Top node
when Top node content is, as is the general case, also in @copying.
In addition there is no way to mark that @top is special and it ends
up being not very good with xsltproc. 

> > HTML: two options
> > * book-like: format the text before the first @node or sectioning
> >   including the title page. Do not output the Top node.
> >   Default for CONTENTS_OUTPUT_LOCATION is after_title

After some experimentation, using after_top too seems better, as
there is a need for a navigation headaer even when the top node
is ignored, and it is better to have the contents after.

> > * non book: do not output the text before the first @node or sectioning
> >   command. Output the top node. Maybe, do not output any title?
> >   Default for CONTENTS_OUTPUT_LOCATION is after_top as is today.
> >   Not outputting the the text before the first @node or sectioning command
> >   is a change, as well as not outputting any title.
> > Default is non book.
> 
> If this is for epub output then it would be fine to have configuration
> options to omit the Top node.

For epub, and more generally if a titlepage is wanted.

> In your "non book" option, I think it is occasionally useful to output
> the text before the first node for testing and short input files
> (the current behaviour AFAIK).  This could be left unchanged.

If you like.

> Again I think the name of the option shouldn't contain the work "book",
> as it is too vague.

I could propose, though I do not like it that much:
OUTPUT_BOOK_INFO_NO_TOP_NODE

> It may be fine not to output anything for @settitle specifically in
> the default output, as long as there are enough headings output for
> other reasons.

There should be the @top line in that case, which is often redundant
with the @settitle or similar @-command title.

> > Note that this is also an attempt to have the conditions ready to put
> > the "Copyright page" out of the @titlepage.  That would call for another
> > change, start the headings not at @end titlepage, but at the first @node
> > or sectioning command.
> 
> In the past, we discussed adding a new command @titleverso that
> could be used for more semantic input instead of specifying the formatting
> of the title page exactly:
> 
> https://lists.gnu.org/archive/html/bug-texinfo/2019-03/msg00029.html
> 
> I don't remember that this discussion came to anything.

Indeed, but I view that more as a second step now.  I now understand that
what you proposed at that time is the way to go.  However, having worked
on the LaTeX output and also with epub that is a book and html made me
want to take another step back to try to have something better and more
logical for the whole beginning before getting to that.

-- 
Pat