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.
