Results of Mallard Planning Meeting
- From: Shaun McCance <shaunm gnome org>
- To: gnome-doc-list gnome org
- Subject: Results of Mallard Planning Meeting
- Date: Sun, 23 Aug 2009 21:17:11 -0500
We had an open meeting to review the Mallard specification.
We ended up meeting for two hours, and didn't get through
everything. We'll be scheduling a followup meeting.
The full meeting log is attached. This is a summary of
what we discussed. We agreed to take all proposed changes
to the mailing list. There were a couple of issues where
we didn't come to an agreement.
There were no issues with the mal_inline content model.
Some issues were raised with specific elements. We
reviewed all inline elements. If I don't mention it
here, it means no discussion was raised.
Phil asked about a way to display error message prominently
at the top of a page, for pages that deal specifically with
how to handle an error in a given circumstance. Shaun asked
if title or subtitle were sufficient, and also wondered if
we should have a generic summary-type block element that
could be used for this an other purposes. Shaun wants to
defer on this until real use cases arise.
Phil suggested that the app tag may be unnecessary. It
was agreed to remove the suggestion in the specification
to use app for window titles. Shaun's reasoning for the
app tag is for generic-named applications: "You can use
Calculator to..." sounds awkward if "Calculator" isn't
clearly marked as a proper noun. Capitalization might
be sufficient in English, but it's not reliable in other
languages. Milo suggested that having application names
marked with the app tag can help translators.
No consensus was reached. We agreed to discuss this on
the mailing list.
Milo asked if we should recommend and implement a style
hint on the em tag for bold text. Shaun hates inline
bold for everything but inline headers. We agreed to
raise this issue on the list.
Milo also asked about how the em tag is read by Orca.
Shaun expressed in interest in working with accessibility
people to have a better aural presentation.
Phil asked why we can't do ubiquitous linking on the
guiseq element. Raising the issue on the list.
Shaun also asked if the content model was too limiting
in that it doesn't allow inline markup in child text
nodes. The example Shaun gave was rightly shot down
as something we shouldn't do.
(At this point I want to interject with something I
didn't bring up in the meeting. I wonder if this will
be a problem if people start embedding Ruby markup in
their text. I think this is something we can address
later in a backwards-compatible way, though.)
Like guiseq, the keyseq element doesn't allow linking
attributes. Should it?
People didn't like the complicated content model and
the type attribute. You can use the type attribute to
select between a combo and a sequence. You can embed
keyseq elements in keyseq elements to have sequences
of combos and such.
Milo raised the concern that sequences might be useful
for our accessibility documentation. We decided to
remove the type attribute and simplify the content to
allow only key elements and text, similar to the model
for guiseq. We will implement sequence as a style hint,
but we will not recommend that style hint at this time.
This way, it's available if we find we need it, but if
we don't, we can silently drop it.
Phil wondered if sys is really all that useful, and also
pointed out that file names could just be done with the
sys element instead of the file element.
Shaun pointed out the sys is necessary for more technical
documentation, like system administrator documentation.
And we agreed that file names are common enough to warrant
their own element.
Questions were raised about the media types and how fallback
rendering works. The specification text should be updated
to address these questions better.
Phil wondered if the content model forced authors to have
image fallbacks for videos, or similar fallback rules.
Shaun pointed out that it's difficult, and suggested that
authors just need to take care of their content.
We reviewed the basic and formal block elements. If I
don't mention it here, it means no discussion was raised.
Phil asked if a separate tag for examples is necessary,
and if we couldn't just use an attribute on the p element.
Shaun pointed out that example does grouping, and that it's
actually used for all the examples in the Mallard spec.
We agreed to make the cite element optional in quotes.
Shaun said he'd like to be able to float figures to the
left or right, like you see on Wikipedia. We agreed this
can be done with a style hint.
That's what we got through. People seemed happy with
using IRC for this review, so we'll do another one to
finish (or get closer to finishing). Milo proposed
doing half an hour after next week's team meeting.
I want to encourage people to reply to this email with
their own thoughts. IRC meetings are nice because you
can get thoughts across quickly, but not everybody can
make it at the same time. So I want to give people a
chance to comment on the mailing list.
<shaunm> hi folks
<shaunm> who's here?
* philbull waves
<PeterHaslam> PeterHaslam does too
<shaunm> I see a lot of joins in the last few minutes
<shaunm> (always hard to tell who's here and who just happens to be idling)
* Gwaihir says hello!
<shaunm> all right, then, let's start
<shaunm> that's the specification, for anybody who doesn't have it already
<shaunm> I'd like to move through things fairly systematically
<shaunm> ugh, I just realized those pages are a little out of date
<shaunm> one minute
<shaunm> all right
<shaunm> let's start with inline
<shaunm> so I want to know two things here: first, does the content model work well?
<shaunm> second, does anybody have any issues with the actual inline elements we have?
<shaunm> think one of them should go, or think we really need to add another
<Gwaihir> for what I've been using so far, I'm happy as it is now
<shaunm> all right
<shaunm> philbull: I remember you proposed nuking <app>
<philbull> Yes, I don't see why we should use <app>
<Gwaihir> (is there something wrong with the Application Names and GUI Labels topics in that page?)
<philbull> Surely the user knows the name of the application that they're using?
<philbull> What is the benefit in highlighting it?
<shaunm> my only concern is applications with generic names
<shaunm> they sound funny when used in a sentence
<philbull> Won't the capitalisation give them away?
<shaunm> in English
<Gwaihir> I agree with shaunm, and also as a translators I really like the idea of differentiating the name of the apps form the rest of the text
<shaunm> in German, for instance, all nouns are capitalized
--> andre (~andre g1 blanicka25 net) has joined #docs
<shaunm> should we not italicize them by default in English? maybe have locale-dependant formatting rules
<philbull> That sounds more complicated.
<shaunm> well, it's an implementation detail, and not something that needs to be normatively specified
<philbull> Hmmm, can you give an example of where an application name used without highlighting would lead to ambiguity?
<shaunm> ambiguity, no
<shaunm> "You can use Calculator to..." kind of reads like "You can start the calculator to..."
<shaunm> except it looks like you just forgot the article "the"
<shaunm> and, as you say, the capitalization gives it away in English
<philbull> In that case, why don't we just write "You can use the calculator to..."
<philbull> That's why it's named "Calculator" after all
<shaunm> good point
<shaunm> maybe we should just refer to all generic-named applications without proper names
<philbull> Yes, I think it looks a bit dorky otherwise.
<Gwaihir> hmmm... I still think that the app tag would be needed... "Use Empathy to have a conversation..."
<philbull> "Use the Empathy IM client to have a conversation..."
<Gwaihir> using the full name...
<shaunm> well, Empathy doesn't use a generic name
<shaunm> the question is, does it need special formatting to make it more legible to the reader?
<shaunm> and, I suppose another question is, does marking the application name help translators?
<shaunm> because on the one hand, the more inline markup you have, I would think the translator burden would be higher
<Gwaihir> it might help them, yes, at least you wouldn't see application names translated
<shaunm> but on the other hand, knowing that it's a proper noun could drastically affect the way translators craft a sentence
<philbull> Surely the translators can be relied upon to recognise the context?
<Gwaihir> yes, true, but there could be first-time translators or even people that have a basic level of English...
<shaunm> ok, so at the very least, I'd recommended using <app> for window titles. and it seems people prefer <gui> for that
<Gwaihir> and there might be not a QA process in reviewing translations...
<shaunm> so I'm going to strike that recommendation and follow the crowd
<Gwaihir> yeah... I was going to raise that one
<Gwaihir> it's more natural to me to refer to a window as an element of the whole GUI
<philbull> I agree
<shaunm> what initially led me to that recommendation was things like capplets, where the difference between a window title and an application name gets kind of gray
<shaunm> but I see your side as well
<Gwaihir> yes, but that's more a GNOME specific issue
<shaunm> I suppose it is
<shaunm> I'll remove that bit of style-forcing from the spec
<shaunm> I think I'm still on the fence on the app element in general
<shaunm> can we take this to the list and move on?
<philbull> I have an issue with marking-up error messages
<philbull> Should I be using <output>?
<shaunm> yeah, so the current recommendation is to use <output style="error">
<shaunm> well, that's for error messages in a command line program
<philbull> Most GUI errors have a title and some text
<philbull> I'm thinking about how users search for error text here
<shaunm> for GUI error messages, is there any reason not to just use <gui>?
<philbull> I'm thinking that, when a topic is written to deal with an error message, that the message should be displayed prominently
<philbull> so the user knows they're found the right page
<philbull> I'd normally do this with an indent
<shaunm> so at the top of the page, the error message, indented?
<philbull> Yes, something like that
<Gwaihir> can you use the error message as the description of the page?
<philbull> Yes, but sometimes it's very long
<shaunm> but the page description doesn't show on the page itself
<philbull> Ah, true
<shaunm> could you maybe mock something up in html and send it to the list for discussion?
<philbull> Well, here's how MS do it: http://support.microsoft.com/kb/824225/en-us
<Gwaihir> using "quote"?
<philbull> Here's how Apple do it: http://support.apple.com/kb/TS2800
<shaunm> I'm kind of thinking that this can be solved more generally, with a block element for "look at me, I'm telling you what's up"
<philbull> What other cases would that be useful for?
<philbull> Maybe notifications?
<Gwaihir> if you want to replicate MSN case you can use a <section><title></title></section> inside the topic
<shaunm> that prevents you from doing block content afterward, by the way
<philbull> Should we be documenting error messages more?
<shaunm> no block content after sections
<philbull> i.e. providing a help button on error messages?
<philbull> In that case, maybe a specific element is needed?
<shaunm> is it not sufficient to just use the error message as the page title?
<philbull> Not always, because you can have the same error messages in different contexts
<philbull> They would look the same in search results, for example
<shaunm> and <subtitle>?
<philbull> Then it will depend on the search implementation
<philbull> Although, if we're linking directly from an error message, it won't matter
<shaunm> I'd like to see some real cases before adding markup
<philbull> OK, maybe we should defer to the list
<shaunm> can we zip quickly through the content model of the inline elements?
<shaunm> most of them are variations on the same thing, so it should be quick
<shaunm> so <app> (which may or may not stay) uses the common content model: linking attributes, style attribute, external-namespace attributes, and then general inline content
<shaunm> (we'll look at the linking attributes in a bit. the attributes in the current spec are outdated)
<shaunm> any issues with that model in general, or with app using the common model?
<shaunm> I'm just going to keep moving through, and I'll stop when somebody says stop
<shaunm> standard model plus the mime attribute, so you can say what kind of code it is
<shaunm> standard model plus mime attribute
<shaunm> standard model. recommended style hints are "output", "error", and "prompt". really intended for command line stuff
<shaunm> standard model
<Gwaihir> one question on the em
<Gwaihir> how does it work with Orca?
<Gwaihir> does it have a particular reading style?
<Gwaihir> or it is read as normal text...
<shaunm> I really really really want to add aural information to the css that gnome-doc-utils outputs
<shaunm> but I need accessibility people to work with me on that. otherwise I'm just guessing
<shaunm> it's probably just read as normal text right now
<shaunm> we currently output as <span class="em">, and then css italicizes it
<Gwaihir> right, another quick one
<shaunm> maybe outputting it as <i> would cause some default special aural treatment
<Gwaihir> should we suggest some recommended style for em?
<Gwaihir> like "strong"...
<shaunm> you mean to get bold text?
<shaunm> I really don't like inline bold text. most technical documentation out there has entirely too much of it
<shaunm> although there is one use case for inline bold that I consider to be perfectly valid
--> baptistemm (~baptiste man06-2-88-167-44-76 fbx proxad net) has joined #docs
<shaunm> which is inline headers
<shaunm> anybody else want to weigh in on that?
<shaunm> ok, let's raise it on the list
<shaunm> <file> uses the common model
<shaunm> <gui> uses the common model
<shaunm> <input> uses the common model
<shaunm> <key> uses the common model
<shaunm> style attribute and external-namespace attributes. notably, it does not allow linking attributes
<shaunm> and then you can do text or gui elements
<philbull> Why doesn't it allow linking attributes?
<shaunm> I suppose I just figured that should be done on the child elements
<shaunm> should we add linking attributes?
<shaunm> I guess there's no real reason to make it special
<philbull> Maybe it would be useful to have a <guiseq> open the item that it's referring to, when clicked in Yelp?
<shaunm> yes, well, that's another can of worms
<shaunm> is the inability to use other inline content too limiting?
<philbull> No, I don't think so
<shaunm> like, do people need to do <guiseq><gui>File</gui><var>recent file</var></guiseq>?
<Gwaihir> I hope not...
<philbull> No, I don't think so. That would be an awkward way of presenting that instruction to the user
<shaunm> again, no linking attributes
<shaunm> has the type attribute to specify "combo" or "sequence". should those just be done as style hints instead?
<philbull> Style hints, if at all
<philbull> If you're telling the user to press them in sequence, you should say that in words rather than with formatting
<shaunm> so there are only two places I can think of where sequences happen
<shaunm> 1) in emacs
<shaunm> 2) when users have sticky keys enabled, for accessibility reasons
<shaunm> obviously, sticky keys affects all keyboard shortcuts, and we can't very well switch them all out
<philbull> OK, I think we should ditch the type attribute and not replace it
<shaunm> in that case, should we ditch the ability to nest keyseq?
<shaunm> it does also provide one workaround for one particular case
<shaunm> see the last example on the page
<Gwaihir> hmmm... I'm thinking of the accessibility guide here... we might need them
<shaunm> Gwaihir: would we need to nest for the accessibility guide, or just specify combo vs sequence?
<Gwaihir> combo vs sequence
<shaunm> ok, so I can considerably simplify the content model if I drop nesting
<shaunm> (I'm thinking that last example is a corner case we don't need to handle)
<shaunm> and I can drop the type attribute, so it's no longer normative
<shaunm> and what I can do is, for now, implement the style hint in gnome-doc-utils, but not recommend the style hint in the spec
<Gwaihir> yeah... I was thinking of another nesting example, but can't really imagine where we would use it
<shaunm> that way, it's there if we need it for the accessibility guide. and if we find we don't need it, we can silently drop it
<shaunm> all right, let me hit the easy ones
<shaunm> <span> <sys> <var>
<shaunm> all of them use the common model
<shaunm> then there's link
<shaunm> you can have an xref, or an href, or and xref and an href
<shaunm> common style and external-namespace attributes
<shaunm> role attribute lets you do title selection
<shaunm> and then inline content
<philbull> Is it going to be used very commonly?
<Gwaihir> one use case might be <sys>/dev</sys>
<Gwaihir> or something similar...
<shaunm> looking at our current usage of systemitem
<shaunm> gconf keys is a common use
<shaunm> vinagre.xml: The &app; application is a Remote Desktop Viewer for the <systemitem>GNOME desktop</systemitem>
* shaunm shakes his head
* philbull throws up
<philbull> hmmm, couldn't we merge file and sys?
<Gwaihir> I think that doesn't count as common use :)
<shaunm> file is certainly a sys specialization
<philbull> I suppose file is very commonly used
<shaunm> so in docbook, there are at least half a dozen elements that are systemitem specializations, effectively
<shaunm> and file was the only one that I thought was worthwhile
<shaunm> I do agree that, if we didn't have file, we'd use sys for it instead
<philbull> I think it could be easy to misuse sys
<philbull> I definitely think that we should keep file, since it's very common
<shaunm> I think sys is a necessity in some of the more technical documentation
<shaunm> like system administrator guides
<philbull> ah, OK
* philbull changes his mind
<shaunm> that just leaves media
<shaunm> big hairy beast
<shaunm> common linking, style, and external-namespace attributes
<Gwaihir> I have a few considerations, but they are more XSLT related
<philbull> Does the src attribute support stuff on the web?
<shaunm> philbull: yeah, just give it a URL
<philbull> So, could Yelp conceivably embed Flash videos?
<shaunm> conceivably, yes. although only image media is currently implemented
<philbull> I'm very keen on videos at the moment
<philbull> (Flash was only an example. There's Silverlight too...)
* philbull ducks
<shaunm> OR OGG THEORA!!!
<Gwaihir> there's also ogg
<shaunm> ok, so are there any issues with how content selection works? do people even understand that stuff?
<philbull> How about the type="application"?
<shaunm> so the idea is that for type="video", you would add video controls and such.
<shaunm> but in the case of, say, a youtube video, you're really embedding a player application with its own video controls
<shaunm> one could imagine embedding interactive applications as well
<philbull> Will <media> validate if your fallback media type is the same as the primary media type?
<philbull> e.g. your fallback type for a video is another video, which you can't display on paper?
<Gwaihir> shaunm: will the video one use the <video> tag in generating HTML?
<shaunm> Gwaihir: that's the notion, yeah
<shaunm> philbull: well, you could fallback to a fallback to a fallback
<shaunm> like maybe you provide a theora video, but failing that, an avi, but failing that an image
<philbull> But if all of the fallbacks fail, what happens?
<shaunm> so it's hard to ensure with the content model that you eventually have an image or text fallback
<shaunm> then you get nothing
<shaunm> I think it's just one of those things where authors need to take care of their own documents
<shaunm> also, the way fallbacks are implemented, one video could, in theory, fallback to two images
<shaunm> or whatever else
<shaunm> it just falls back to general inline content, which may or may not contain inline media, which may or may not have to fallback itself
<shaunm> it's been an hour and a half. can you guys continue?
<shaunm> (I'm kind of doubting we'll get through everything today)
<Gwaihir> I've no problem going on a little bit more
<philbull> i should eat soon, but I don't mind going for a bit longer
<shaunm> yeah, I'll need to make some food soon as well
<shaunm> half an hour?
<Gwaihir> sounds good
<shaunm> basic block elements
<shaunm> common style and external-namespace attributes, general inline content
<shaunm> I assume nobody wants the <p> element removed?
<Gwaihir> we can use it...
<shaunm> heh, yeah
<shaunm> code blocks. style and external namespace attributes. adds the mime attribute. general inline content
<philbull> will Yelp use the mime type to do code highlighting?
<philbull> (in <code>)
<shaunm> philbull: it's a low priority feature for me, but that's the sort of thing you can do with the mime attribute
<shaunm> screen has the same content model as code
<shaunm> block media is basically the same as inline media, except it's a block
<shaunm> fallback content is block content instead of inline
<shaunm> and it doesn't have linking attributes, because block elements don't
<shaunm> style and external-namespace attributes, general block content
<shaunm> used to set examples off from the normal text
<shaunm> (this is mostly getting in to the realm of stuff you use for more technical documentation)
<philbull> Do we need a separate tag?
<philbull> Wouldn't a style hint for <p> suffice, or is this sufficiently common?
<shaunm> well, example groups
<shaunm> so the current rendering has that sort of gray bar to the left of all the block content in one example
<shaunm> <example> is being used for all the examples in the mallard spec
--> pcutler_ (~pcutler c-75-72-118-230 hsd1 mn comcast net) has joined #docs
<shaunm> ok :)
<shaunm> formal elements, which are block elements that allow a title
<shaunm> common attributes, optional title, block content
<shaunm> we've merged all the admonitions into one element, selecting with a style hint
<-- jrb has quit (Remote closed the connection)
<shaunm> common attributes, optional title, mandatory cite, block content
<shaunm> am I being too pedantic in demanding a cite?
<philbull> I think so, the citation could have been made in the text above/below
<shaunm> (I think what I'm going to do is send an email to the list with all proposed changes, so others have a chance to comment)
<shaunm> and, just so it's in my backlog, we'd talked about allowing info elements in at least some block elements. I'll put that on my list of deferred items
<shaunm> figures: common attributes, optional title, optional desc, block content
<shaunm> mostly intended for images, but figures are sometimes used for tables of information or other crap
<shaunm> note that images don't need to be in figures
<shaunm> I'd kind of like to add a way to float figures
<shaunm> like the figures you see on wikipedia, for example
<shaunm> but that can be done with a style hint, I think
<philbull> I agree
<shaunm> all right
<shaunm> we've got two more formal block elements. let's try to finish them off
<shaunm> same content model as figure
<shaunm> generally used to name a code listing or a terminal session or the like
<shaunm> really intended for more technical documentation
<shaunm> same content model again
<shaunm> again more for technical documentation
<shaunm> all right
<shaunm> so we didn't get to lists, tables, informational elements, and the general page and section stuff
<shaunm> was the irc meeting useful for this? should we try to do another to get through the rest? or should we just take it all to the list?
<philbull> IRC was fine
<philbull> just a lot to get through!
<Gwaihir> absolutely great
<shaunm> all right, I'll type up some minutes and send all the proposed changes and open items to the list for discussion
<Gwaihir> can we make an half hour after next sunday meeting?
<shaunm> Gwaihir: you said you're not available next weekend, right?
<Gwaihir> not exactly...
<Gwaihir> I'll be moving in a new place... it depends if the USB Internet key works
<shaunm> ah, ok
<shaunm> all right
<Gwaihir> I tested in and it's working... now
<philbull> ok, I'm going to go and eat
<shaunm> yeah, me too
<shaunm> I'll send a meeting proposal to the list
] [Thread Prev