projectmallard / projectmallard.org Goto Github PK

Currently you can only put a page into a single series with next links. If you specify multiple nexts for a page, bad things happen. Would it be possible to define series in a way that allows individual pages to belong to multiple? Perhaps the group attribute could be used.

<link type="next" xref="foopage3" group="foo"/>
<link type="next" xref="barpage3" group="bar"/>

And then perhaps the links element could select the series with the groups attribute.

<links type="series" groups="foo"/>

But what do the previous and next links do? We could use the groups attribute on those too, but the UI could get ugly. Can we dup pages somehow so it's built/displayed differently based on the series you're in?

Document the <note> element and which values are valid for the style attribute.

Example:

<note style="important">
  <p>This is important.</p>
</note>

<note style="tip">
  <p>This is friendly tip.</p>
</note>

I found it by looking at the source on the Project Mallard website but it seems to be undocumented.

Conditional processing should be able to check information about the current page or the entire document. This is useful when doing boilerplate includes that depend on things like status or links. It's also useful when reusing pages in different documents, where you might want to display certain things only in certain documents. A few candidates:

• Check the current page and section id.
• Check the revision status, possibly pegged to a version. Or check the version.
• Check tag values, pending issue #7.
• Check if other pages exist in the document.

I have implemented serialization of the class hierarchy in g-ir-doc-tool, and the resulting tree for a class with multiple inheritance (interfaces) is full of redundancy, for example :

        <tree>
          <item>
            <link href="https://developer.gnome.org/gobject/unstable//gobject-The-Base-Object-Type.html#GObject">GObject.Object</link>
            <item>
              <link href="https://developer.gnome.org/gobject/unstable//gobject-The-Base-Object-Type.html#GInitiallyUnowned">GObject.InitiallyUnowned</link>
              <item>
                <link xref="GES.Object">GES.Object</link>
                <item>
                  <link xref="GES.Source">GES.Source</link>
                  <item>
                    <link xref="GES.UriSource">GES.UriSource</link>
                  </item>
                </item>
              </item>
            </item>
          </item>
          <item>
            <link xref="index">GObject.GInterface</link>
            <item>
              <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html//GstChildProxy.html">Gst.ChildProxy</link>
              <item>
                <link xref="GES.Object">GES.Object</link>
                <item>
                  <link xref="GES.Source">GES.Source</link>
                  <item>
                    <link xref="GES.UriSource">GES.UriSource</link>
                  </item>
                </item>
              </item>
            </item>
            <item>
              <link xref="GES.Playable">GES.Playable</link>
              <item>
                <link xref="GES.Source">GES.Source</link>
                <item>
                  <link xref="GES.UriSource">GES.UriSource</link>
                </item>
              </item>
            </item>
          </item>
        </tree>

as each branch from the ancestor "leaves" to the child has to be fully specified.

If defined in terms of vertices, with "implicit nodes", the structure would be much cleaner / easier to parse:

<vertex from=GInterface to=GstChildProxy />
<vertex from=GInterface to=GES.Playable />
<vertex from=GObject to=GInitiallyUnowned />
  <vertex from=GstChildProxy to=GES.Object />
  <vertex from=GInitiallyUnowned to=GES.Object />
     <vertex from=GES.Playable to=GES.Source />
     <vertex from=GES.Object to=GES.Source />
       <vertex from=GES.Source to=GES.UriSource />

Currently only pages and sections can do automatic linking. There have been a lot of requests to be able to link to arbitrary blocks. Issue #6 proposes letting formal blocks participate in automatic links, which will be a lot of work. This issue is for the simpler case of making formal blocks be inline link targets.

A very common validation error is that people have comment elements intermingled with sections, or after all section elements. They use comment either to remove some section or to make notes about what sections to add in a particular place.

Comments can't go in these places now, because they're just regular block elements. We don't want to allow any block content in these places. But we could special-case comments.

Relatedly: should comment elements intermixed with sections be able to hold a section child instead of blocks? Kind of crazy, but useful, and I've seen people try to do it.

Sometimes a lot of pages share a number of info stuff in common (license, credits). It's a pain to maintain those redundantly. It's a pain to XInclude them each separately. It's a pain to use XInclude with XPointer to grab multiple subelements, sadly.

We could allow info to contain info elements, so that in your info you could XInclude a file that has a top-level info. Alternatively, we could allow pages/sections to have more than one info child.

Look carefully at the performance cost and the fallback behavior.

We might be able to add conditionals for title and desc elements without breaking the existing content model by using informational elements, e.g.:

<info>
  <title type="display" if:test="platform:fedora"/>
</info>

One issue is that we can only have one title, but more than one could match. We could treat the multiple informational titles as if they were a choose/when block, so the first match wins. And we'd have to make this work across link titles, sort titles, etc. It's a non-trivial addition, and it could have hiccups we'd only discover in trying to implement it.

Link groups are currently limited to topic links. Link grouping could be useful for other types of links as well. I'm not sure how to do it for guide or seealso, but perhaps we could do it for section links by adding a group attribute to section elements. Alternatively, provide some way of specifying a range. Alternatively, let the groups attribute of the section element reference IDs.

This could be useful to add some expository text between related sets of links, or to put a title above links of a certain type.

Low priority, as sections are generally used in a lightweight fashion in Mallard. We don't often have large pages with lots of sections.

Replace the version/docversion/pkgversion attributes with a single version attribute that can take a space-separated list of version tokens. It's good to be able to record versions of different things, but the split between page, document, and package just don't match up to reality for many documents. Instead, they might want to record the version of an upstream, or of a framework, or of a content pool, or of a deliverable. Let the version attribute be a list of either bare versions of colon-delimited key-value pairs, e.g.:

<revision version="1.0 upstream:2.2 myframework:2.8.2"/>

Currently, the only top-level element is page. We could add a stack element that contains one or more page elements. It should probably also have an info element, and perhaps a title, though we need to figure out to what extent stack info is inherited by page info. This has a few advantages:

• It can be easier to author and track a related set of pages.
• It can allow people to put actual pages into subfolders, and just XInclude them into a stack not in the subfolder, to make management of large documents better.
• Pages could be put into stacks for installation, reducing the number of on-disk files. This can be nice for plugin pages, so you just have one file for each plugin package.
• It actually allows an entire document to be distributed as a single file.

Additionally, the stack element can have a type attribute that can affect its pages. Extensions can add stack types. We'd define two in the core: set and series. A set is the default and adds no semantics. A series writes/rewrites next links in its child pages to create a series. Next links are cumbersome, and this is a much easier way of making a linear series.

Question: can stacks contain stacks? What's the semantics when a series stack contains stacks?

Useful when you want to provide code samples in different languages, or provide different commands on different systems without the overhead of conditionals. Something like:

<ui:tabs>
<ui:tab>
  <title>Tab 1</title>
  <p>Tab content</p>
</ui:tab>
<ui:tab>
  <title>Tab 2</title>
  <p>Tab content</p>
</ui:tab>
</ui:tabs>

Would probably be nice to provide one (or more) tabs with non-extension content, for fallback. listing is natural for code blocks and perhaps screens. A generic div element could be useful (issue #15).

Can we do tabs on sections? The content model restricts us more here. Instead of a wrapper element, we might have to indicate tabiness with an attribute.

Can we synchronous tab switches? If you use tabs for the same thing (preferred programming language, operating system), then you really just want to switch them all and be done with it. Bonus points for syncing across the whole document.

We should probably provide a way to set the default tab, defaulting to first.

Possibly add an element to identify package names, other than doing <sys style="package">. It's heavily used in installation guides and various devops environments, and enables automated testing to ensure correct and current package names.

Once Mallard 1.1 is released, go through the tutorials and anything about about to update links.

There should be more test tokens available to check for the following aspects of the platform:

• system default web browser
• distribution

Sometimes it's useful to put something in a guide without linking back up to it, or to put a link into a seealso without the target linking back. Reciprocal links are awesome and one of Mallard's defining features, but sometimes it's nice to block them.

Maybe an attribute that specifies whether the link goes in, out, or both, with both the default?

I want mallard to work with python-django.
What I want is to fetch document from mallard and display it in HTML. using django.
Is there any possibles?
Sorry. Little urgent. So, Opened an issue.

In Mallard 1.0, the id attribute is mandatory on section elements. This is the only way you can link to sections. In practice, people tend to use a lot of lightweight sections, and the id requirement is cumbersome. Possibly enforce mandatory IDs on guide page sections, though that probably involves too much cruft in the schema.

example is the only block container element that can't take a title. Let's just make it a formal element by allowing a title, and whatever else might get added to formal elements down the road (id, info).

The listing, example, and synopsis elements are most useful for developer docs, so it makes sense to group them together for a tutorial.

All the current formal elements have specific semantics with associated presentation expectations. It could be useful to have a generic element that acts like a formal block but carries no semantics and no presentation expectations aside from having its title look like a block title.

This could be particularly useful for extensions that want to add formal block elements. The current fallback processing for blocks is that the children of the element are processed in restricted block context, as if the unknown block itself were replaced by its children. This is no good if the block has a title. The core title element can't be reused, because it doesn't make sense in that context. So extensions have to add an extension title element, which is then ignored in restricted block context.

With a formal div element, the fallback behavior could be that the unknown block is processed as if it were a div element, except that child elements are processed in restricted block context. This lets the title get picked up, and would be crucial to letting extension blocks do automatic linking, if we go down that route.

Thumbnails are useful for various extensions and specialty styles. Add a thumb element to info. Look at allowing multiple thumbs with type/role, just like title and desc.

Currently info is only allowed on page and section elements. Sometimes it's useful to provide metadata for other pieces of the document. The info element can safely be added to all formal block elements.

Mallard uses the mime attribute in two places: media and code blocks. Using a MIME type to specify the content type seems natural, but in practice it's hard to remember the right MIME type. This is especially true in code blocks, where there's not a registered MIME type for many languages. People just have to look up the x- MIME types that Yelp happens to understand.

For code blocks, it would be better to use a simple identifier like "c", "javascript", or "xml". That's what code highlighter libraries use anyway. And if we put that in a type attribute, we can take advantage of Ducktype's shorthand for type attributes, e.g.:

[code python]
def frobnicate(self):
    pass

Compare this to:

[code mime="text/x-python"]
def frobnicate(self):
    pass

We could even support multiple values in the type attribute. Space-separated type attributes isn't unprecendented in Mallard. This can help you match different values accepted by different tools, or provide more specific values with fallback, e.g.:

<code type="xslt xml">

Or in Ducktype:

[code xslt xml]

For media elements, the type attribute is already in use, and works well for what it does. Specifying the actual type is less frequently used in this case, although it's important for application-type media elements. Maybe we just keep the mime attribute for that. Or maybe we let media type be a space-separated list, where the first comes from the controlled list of "image", "video", "audio", and "application". Or maybe some other syntax.

A number of potential extensions and uses would be easier with a generic tagging system, or a way to put pages into arbitrary categories. To some extent, guide links and other info links serve as a categorization system, but they require a page or section to exist to head each category.

There should be some way of putting tags in groups or namespaces, in part to avoid collisions, and in part to show what the intended use of a tag is. One option, directly from the earliest tag implementation in the experimental facets extension, is to have tags belong to a tag key, such as:

<tag key="lang" values="c python"/>
<tag key="tech" values="gtk clutter gstreamer"/>

Another option is to use something like the syntax for conditional tokens, such as:

<tag values="lang:c lang:python tech:gtk tech:clutter tech:gstreamer"/>

We need to define what happens with multiple declarations (first-only, last-only, or merge). And whether there's any sort of inheritance to subsections.

Hi,

I'm at GUADEC and learning about GNOME documentation and when looking at Mallard I got

Probably this is a CSS issue when you use Webkit and HiDPI. Please let me know if you need more info.

To maintain link integrity, we should have a way to specify additional IDs that a page/section assumes. This is useful, for example, when deleting a page to redirect anything going to an old ID to new content. Open questions:

• Can pages assume section IDs? Can sections assume page IDs? Can sections assume section IDs outside their parent page?
• Who wins if there's a conflict? If one of those conflicts is the original ID?
• Can all the automatic linking be made to automatically follow anchors in both directions? Should it?
• What's the performance cost of adding this level of indirection to node lookups?

Currently, any info links have to be xref links to other pages or sections within the document (or potentially in a larger help system with an extended xref syntax). This goes for topic, guide, seealso, and next links, as well as any other links defined by extensions or future Mallard versions.

Sometimes it's useful to link to an external page within topic links or seealso links. We could allow this by allowing an href attribute on info link elements. But then we need a way to get information like title, desc, thumb, etc. So we could allow that information as child elements to the link element.

<info>
  <link type="topic" href="http://projectmallard.org/">
    <title>Mallard</title>
    <desc>We built the help system.</desc>
  </link>
</info>

Basically, the contents of the link element are treated as if they're the contents of an info element for the thing you're linking to. This allows stuff like sort and text titles, revision info, etc. The current content model for info link elements is just external. Switching it to info contents, which allows external, shouldn't present any compatibility issues.

Provide a lang attribute for the <code> element.

<code lang="python">
class Cat(object):
    def talk():
        """Make some noise."""
        print('Meow')
</code>

This would semantically declare the language of the code.
Which could be used to apply syntax highlighting.

Create a tutorial for the note element, running through some of the different note styles.

Mallard basically follows the HTML table model, deviating only for styling purposes (border, lines between, alternate shading). But it doesn't have a th element. th is good for accessibility, especially with row headers that can't be indicated with something like thead.

We replaced the mime attribute on code, screen, and cmd with the type attribute, which takes a space-separated list of simple type tokens. Let's do something similar for media. The media element already uses the type attribute for the high-level type: image, audio, video, application. We could override type attribute in two ways.

1. We could do something like type="video/webm" or type="video:webm", where the left part is still the high-level type, and the right part is more specific. The trouble with using a slash is that it looks like a MIME type, but we wouldn't actually be using MIME types.

2. We could do a space-separated list, where we require that the first token is still the high-level type, such as type="video webm".

Option (2) is more like how we do code types. Either option is going to come with fallback problems, such that pages written with this syntax won't render correctly with older tools. For compatibility in the other direction, option (1) would require newer tools to continue to recognize a simple high-level type. Tools should continue to do so anyway, but with option (2) it feels more natural, because a single token is just a regular case of a space-separated token list.

There should be a way to easily convert Mallard/Duckype content to one or more of the popular doc formats out there:

• DocBook
• Markdown
• AsciiDoc
• reStructuredText

Existing conversion tools, such as pandoc, can then be used to convert content from one of these formats to another.

This will help in adoption of Mallard/Duckype in projects that already use some of the formats mentioned above.

For a very long time, Yelp has supported the hi element in the experimental namespace. This is an inline element that highlights the text with a yellow background. It's useful to show what's new when progressively building on a code sample, for example.

This is a simple element to implement and doesn't obviously fit into any other extension, so we should just add it to the Mallard core. It's similar to the HTML mark element, so maybe it should be named mark. We should recommend style hints for "added" and "deleted" and maybe other common reasons to highlight text.

We allow multiple title elements in info, using the type and role attributes to ascertain when to use which. But we always use the same desc element. When it's useful to provide alternate titles, it's sometimes useful to provide alternate descs. Allow multiple desc elements with the type and role attributes, using the same rules as title for when each is used.

Create a tutorial (or more) to run through various inline elements. The code, cmd, input, and output elements are already in the "Code and Commands" tutorial. The media element is already in the "Images and Videos" tutorial. Linking is its own thing, tho it might be worth mentioning ubiquitous linking. That leaves app, em, file, gui, guiseq, hi, key, keyseq, span, sys, and var. Maybe this should be more than one tutorial. It might make sense for var to be covered in "Code and Commands".

If we add test tokens "true" and "false" to Mallard Conditionals that always evaluate as you'd expect, it provides another way people could define tokens. Rather than having to plug into the Conditionals processor, you could define them with entities, which could be overridden with different includes or with the build process. For example:

<!ENTITY mycondition "true">
<if:if test="&mycondition;">

Or with Ducktype:

[[duck:entity mycondition="true"]]
[if:if test="$mycondition;"]]

Currently, all block elements define their own schema pattern for attributes. If you want to write an extension that adds attributes for all blocks, you have to override all of them. This is a pain, it's not future-proof, and it misses potential extension blocks. There should be a mal_block_attr pattern, which the individual mal_block_*_attr would reference.

Add a section to about/learn/code showing how to specify code type for syntax highlighting. Use the type attribute from Mallard 1.1. Make a brief mention of the mime attribute from 1.0.

Sometimes we use desc just to stuff extra keywords in for non-full-text search. A keywords element would help avoid that.

Create a tutorial that shows different link types (topic/guide, seealso, next), shows how to use link titles and link titles with roles, and shows link groups for topic links.

Currently only pages and sections can do automatic linking. There have been a lot of requests to be able to link to arbitrary blocks. Automatic linking is untenable for things without an id and a title, but we can make it work for all formal block elements. This requires adding info as a child of formal blocks.

Conditionals currently only work on blocks and list items. People want it on pages and sections. Implementation might be tricky.

Create a page listing tools that support Mallard, along with a brief description of what each tool is and does. Maybe about/tools.page or about/tools/index.page. Off the top of my head: yelp-xsl, yelp-tools (including yelp.m4), meson (help system integration), yelp, itstool, pintail, mallard-ducktype. Maybe also mal2dot, mal2latex, and db2man, though those are less fleshed out.

Mallard 1.0 does not allow you to easily swap out the type of the id attribute for page and section elements. Cache files need to change the type from NMTOKEN to something more permissive, like text, because sections in cache files are of the form page_id#section_id. The proposed solution for cache/1.0 is to just use new patterns cache_page_attr and cache_section_attr which are defined to look just like mal_page_attr and mal_section_attr, except the id change.

We should fix this for 1.1 so that cache/1.1 can just easily override the id attribute, and reuse mal_page_attr, mal_section_attr, and any extensions to those. If we introduce cache_page_attr and cache_section_attr, let's go ahead and keep them, though they may default to being empty. They could be useful extension points (e.g. for Sites).

If we let blocks take IDs and participate in linking, let's make sure we get this right the first time for them.

Sometimes it's useful to have a bit of intro text to a set of links made with the element, after the title. Do we want to go down the route of allowing any blocks? That seems crazy. Maybe just allow a single desc as an intro paragraph?

In addition to a primary status ("draft", "ready for review", "final", etc.), it's often useful to be able to add extra status flags that you can have multiple of ("needs technical review", "needs content review", "needs reorg", etc.). Two options:

1. We make the revision status attribute take a space-separated list, defining the first token as the primary status. This has some compatibility issues.

2. We add an extra revision attribute like flags to record these.

Sometimes it's useful to have a link to an external site mixed in with e.g. seealso links. Obviously we can't make those reciprocate, but we can add the links on the page itself. Need to think about link text.

Users can specify different roles on link titles, allowing different link text to be used in different contexts. But they all share the same sort title.