bug-texinfo
[Top][All Lists]
Advanced

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

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


From: Gavin Smith
Subject: Re: manual organized in topics in Texinfo (similar with Mallard)?
Date: Sat, 22 Jan 2022 09:52:27 +0000
User-agent: Mutt/1.9.4 (2018-02-28)

On Mon, Jan 17, 2022 at 02:32:27PM +0100, Patrice Dumas wrote:
> Hello,
> 
> I stumbled by chance on the Mallard format which is used in the GNOME
> project for their documentation:
> http://projectmallard.org/about/learn/index.html
> http://projectmallard.org/1.1/
> 
> What I found interesting is that the documentation is organized by
> topics instead of being organized as a book.  It occured to me that
> this would correspond to a Texinfo manual based on @node and on
> menu navigation.  In my view, "guide" pages could be nodes that link
> to "topic" nodes using a menu with the links to topic nodes,
> appearing in any order in the menu.  A topic node may also appear
> in multiple guide nodes.  Topic nodes would also link back to the
> guide nodes they appear in.
> 
> Are you aware of Texinfo manuals in the wild following thay kind of
> structure in topic, and with that conceptual approach to documentation?

I'm not aware of any, as far as I understand what the approach is.

I haven't experienced Mallard documentation as far as I remember.  Are
there good examples of Mallard documentation showing the benefits of its
philosophy?

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

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?

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

This actually matches my experience of using help in Microsoft Office
(in various previous day jobs).  It seems you can't simply read through
the manual for Microsoft Word cover-to-cover, even if you wanted to.
What you get is a lot of disconnected individual help pages.  For example
if you knew about tab stops, you could find this page:

https://support.microsoft.com/en-us/office/insert-or-add-tab-stops-06969e0f-2c81-4fe0-8df5-88f18087a8e0

but it is not apparently part of any larger manual.  This is not great
in my opinion because it means you can't discover features you didn't
know about.  The Mallard documentation seems better in that regard with
links to superordinate "guide" pages through which a user could access
other parts of the manual.

I found this page which discusses another documentation system, "DITA" and
the benefits of "topic-based architecture".

https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/topicbenefits.html

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

> 
> This could have some "real life" use, for example we have in the Texinfo
> manual some parts about Emacs that could also appear in some collection
> of emacs manuals, it is not easy to do that naturally in Texinfo for
> now.
> 
> -- 
> Pat
> 



reply via email to

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