bug-texinfo
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Gavin Smith
Subject: Re: more consistent ignoring before node and sections and Top node
Date: Sun, 20 Feb 2022 10:42:25 +0000

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.

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.

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".


> Here are my proposals:
> 
> Info: always ignore text before the first @node or sectioning command.
> It can be in the Info file as it is now, invisible except when looking
> at the info file, but how text is hidden is an implementation detail.
> Always output the top node.  No changes.

I agree, no changes for Info output.

> 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".

> 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.

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.  I expect it would be fine, though, as DocBook
tools would probably supply their own table of contents.

> LaTeX and TeX: book-like. Title information is used, text before first
> @node or sectioning is formatted, Top node is not output. No change.

Good.

> 
> 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
> * 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.

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.

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

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.

> 
> 
> Remarks, comments?  See anything in the proposed changes contrary to
> some usage?
> 
> 
> 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.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]