Some questions about mallard

Hi,

On Tue, Jun 21, 2011 at 5:31 PM, Shaun McCance <shaunm at gnome.org> wrote:
> By the way, if you want to be bleeding edge, the new stylesheets in
> yelp-xsl support more features more completely than gnome-doc-utils.
> There are also command-line utilities in yelp-tools to build, check,
> and manage your documents.

Thanks for the feedback, I think I saw a blog post about it indeed.

>> * while mallard aims to limit the amount of markup, it adds some
>> markup that was not needed in docbook: a table cell or note requires
>> to add a <p> tag. I understand it could be some other tag as well, but
>> I feel that just putting some text is common enough to have an
>> implicit paragraph added for us if we omit it.
>
> You're not alone. This is probably the most common complaint.
>
> Mallard is very strict about every element, taken in context, taking
> unambiguously block or inline content. This has a few advantages:
>
> * You get much simpler and more understandable content models.
> * It makes things much easier on processing tools, especially tools
> that try to massage or extract data, like translation tools.
> * Fallback behavior for extension elements can be well-defined, and
> tools always know which fallback rules to apply.
>
> The downside is that elements like <item> and <td> have to require
> block content in order to allow block content. I've mentioned two
> ways to address this in the past, but they both feel hackish, and
> neither got an enthusiastic reception.

I understand that it makes things easier to maintain, but when we just
want a small text, it really adds up a lot of markup, especially for
tables (we have to tables where each cell just contain a number,
leading to 16 characters of markup to encapsulate 1 or 2 characters of
content). Docbook requires a para (or simpara?) only when we need more
than just text if I recall properly.

For example, the "desc" element in figures does not need a <p> to add
text, which is great, but I suppose that it just can not contain any
block element at all.

I did not see any discussion about it, do you have some pointers to
what you proposed and why it does not work?
Note: I'm not complaining here, just trying to understand.

>> * is bibliography support planned? It is pretty heavy in docbook and
>> probably hard to get right, but in our case (scientific software) it
>> is very convenient. It can be writen by hand for now, but mallard has
>> some restriction on what links can point to (see below).
>
> Certainly not in the core language, but Mallard is designed to be
> extended. I haven't had a need for bibliographies, so I haven't
> worked on them.
>
> I do have a half-baked plan for an extension for glossaries and
> indexes. It's really just a way to collect entries and links from
> multiple pages, so it might serve your needs for bibliographies
> as well.
>
> How would you like bibliographies to behave? Do you want a single
> page that collects all entries, or a listing for each page? Do you
> need semantic entries like DocBook's biblioentry, or are you fine
> with formatted entries like bibliomixed?
>
> To do these kinds of things right, we really need input from people
> who have real use cases.

I guess that a good enough use case would not need so many changes to
mallard itself, but most could be done in a smart external tool.
In docbook, I used biblioentry, but this was pretty unpleasant. We
have semantic description of entries as bibtex or similar format and I
think that reusing such a format is the best option, especially as I
prefer having the bibliography as a separate page. It may also be
possible with minimal (if any) changes to mallard itself.

For example, one could add references as <link xref="biblio#refid">.
The biblio page can be handwritten, with only paragraphs with the
proper IDs and span with a good set of style hints. As handwriting it
can be cumbersome, an external tool could extract required references
from mallard pages, then build the "biblio" page for these references
based on a separate bibtex file (or some XML port of bibtex, which
already exists and is less insane to parse).

This would be more than good enough for me, the main problem is that
currently a link can not point to a paragraph.
Does it seem possible? If you already have a working system for
glossaries, I guess it can be adapted to fill this gap as well.

[...]
> As for figures, why not just include them in every page where you
> want to talk about them? It's expensive in print, but cheap online.
> With the new collapsible block extension work, they can be really
> unobtrusive.

Indeed, but I was thinking about mentioning a figure in the text on
the same page, something in the line of "this is illustrated in Figure
3", where docbook autofills figure number for us, but as you point
out, text generation for links makes it much more complicated.


> gnome-doc-tool (and the new tools in yelp-tools) probably works
> fine on OSX, provided you have the right dependencies. I know
> it works on other BSDs. I believe OSX ships with libxml2, but
> not libxslt, so you'll probably need to install that.
>
> The build tools are just shell scripts, so they won't work in
> Windows without Cygwin. The XSLT, however, is reusable, and you
> could use it and build on it with a different XSLT processor and
> build chain. It does use some EXSLT extensions, but those are
> fairly widely supported.
>
> I am interested in seeing Mallard on other systems. I know one
> person is working on Android deployment right now, which is cool.
> I just have a limited amount of free-time development time to
> work on projects like that.

I recently realised that our build script for docbook does not work on
windows out of the box anyway, so it is hardly a hard requirement
right now. It is good to know that it is not explicitly linux-only.

Thanks.

-- 
Aurélien Naldi