Re: manual organized in topics in Texinfo (similar with Mallard)?

[Patrice Dumas]

On Sat, Jan 22, 2022 at 09:52:27AM +0000, Gavin Smith wrote:
> 
> I haven't experienced Mallard documentation as far as I remember.  Are
> there good examples of Mallard documentation showing the benefits of its
> philosophy?

The Gnome documentation, that can be viewed with yelp is probably the
good and (most probably) more or less only example.

> It seemed like an interesting idea that "plugins" could add topics to
> a manual with a kind of reverse linking.  You can imagine this kind of
> thing for Emacs modes, for example.

I agree.

>  I'm not sure how well this works in practice.

> I don't feel I really understand the Mallard approach.  How does this
> work for reading a whole manual?
> 
> For example, http://projectmallard.org/1.1/index.html lists
> some sub-topics ("Pages", "Sections"...).  Say then you click
> on "Informational Elements" and come to
> http://projectmallard.org/1.1/mal_info.html.  This refers to more topics
> like "Credits", "Informational Links", etc.  These topics like "Credits"
> were not listed on the first page.  Is there a master table of contents
> showing all their topics?  Maybe not, if there is no fixed hierarchical
> structure for the manual.

My understanding is that there is not a master table of contents showing
all the topics but several main tables of contents possibly determined
dynamically.  That being said, even after reading more than once the
pages about automatic links, I couldn't really understand what was going
on.

> At the top of http://projectmallard.org/1.1/mal_info_credit.html there
> is a "breadcrumbs" line showing that this topic is subordinate to
> "Informational Elements".  The index http://projectmallard.org/1.1/index.html
> itself is subordinate to another link, "Specifications and Extensions",
> which is at http://projectmallard.org/1.1/index.html, which appears to be
> outside the manual.
> 
> Would I be right in saying that with Mallard, the lines between
> separate manuals are blurred?

That's also my understanding.

> From http://projectmallard.org/about/index.html:
> 
> > Mallard is a documentation format designed to make topic-oriented
> > help as simple as possible. In contrast to linear documentation,
> > which is designed to be read cover-to-cover, topic-oriented help
> > provides users the information they need quickly.
> 
> In other words it's for looking up help on particular problems, but
> not really for reading in depth to learn about a system.

I think that this also crucially depends on how the topics are
organized.  I think that it is possible with this system to also have
in depth descriptions, but the result will probably be much more like
traditional book.

> > As a side note, some elements of Mallard are not easily transposed in
> > Texinfo, in particular the pages are somewhat independent, linked
> > through named menus, and can have internal section structure.  In
> > Texinfo we have whole manuals that are structurally linked only through
> > @direntry and @dircategory.  It is not easy in Texinfo to integrate
> > manual pieces modularily at different levels. They can only be included
> > simply at the Top level, with @direntry and @dircategory.  For instance
> > there would probably be a need for automatic raise/lower section, to be
> > able to tell from the included part in which menu it should be included
> > and maybe have names for menus...
> 
> I guess this kind of free-standing @node would be best titled with the
> @unnumbered command.  The manual pieces are only single HTML pages in
> Mallard so wouldn't include multiple nodes at different levels.

There are also <section> in Mallard which is kind of another level
within a page.  I agree that @unnumbered would be a relevant command,
but it would not correspond to a fixed level, the 'true' level would be
determined by the page it links from.

-- 
Pat