From philip.chimento at gmail.com  Sun May  1 15:30:02 2011
From: philip.chimento at gmail.com (Philip Chimento)
Date: Sun, 1 May 2011 21:30:02 +0200
Subject: Index of all topics in a set of Mallard pages
Message-ID: <BANLkTikaLxVmzsapS1SA7gks_faL_LDmNA@mail.gmail.com>

Hi,

Is there any facility in Mallard for creating an alphabetical index of
topics, even ones that are not linked to on the main 'index.page'
guide page?

What I tried is to create a section on the main index.page:

<section id="full-index">
  <title>Index</title>
</section>

and then a separate guide page, full-index.page, which every topic
page links to using something like:

<link type="guide" xref="full-index"/>

This works fairly well, except for three things:
- You have to manually add a link on every topic page.
- When viewing with Yelp, where each page normally shows its hierarchy
at the top, (e.g. Foo Guide ->  Foo Topic) it now also shows a second
entry (Foo Guide ->  Index ->  Index of all help topics).
- There is a see-also link on the bottom of every topic page that
points to the index.

Is there perhaps some sort of style="no-see-also" attribute possible
that one can use to suppress these see-also and hierarchical links to
the index?

Regards,
-- 
Philip Chimento


From shaunm at gnome.org  Sun May  1 17:25:03 2011
From: shaunm at gnome.org (Shaun McCance)
Date: Sun, 01 May 2011 17:25:03 -0400
Subject: Index of all topics in a set of Mallard pages
In-Reply-To: <BANLkTikaLxVmzsapS1SA7gks_faL_LDmNA@mail.gmail.com>
References: <BANLkTikaLxVmzsapS1SA7gks_faL_LDmNA@mail.gmail.com>
Message-ID: <1304285103.2137.253.camel@recto>

On Sun, 2011-05-01 at 21:30 +0200, Philip Chimento wrote:
> Hi,
> 
> Is there any facility in Mallard for creating an alphabetical index of
> topics, even ones that are not linked to on the main 'index.page'
> guide page?
> 
> What I tried is to create a section on the main index.page:
> 
> <section id="full-index">
>   <title>Index</title>
> </section>
> 
> and then a separate guide page, full-index.page, which every topic
> page links to using something like:
> 
> <link type="guide" xref="full-index"/>
> 
> This works fairly well, except for three things:
> - You have to manually add a link on every topic page.
> - When viewing with Yelp, where each page normally shows its hierarchy
> at the top, (e.g. Foo Guide ->  Foo Topic) it now also shows a second
> entry (Foo Guide ->  Index ->  Index of all help topics).
> - There is a see-also link on the bottom of every topic page that
> points to the index.

You could try using the experimental facets extension.

http://blogs.gnome.org/shaunm/2010/12/16/more-faceted-navigation/
http://projectmallard.org/facet/1.0/

Here's the gist. Create a page that collects all the links.
Set the type attribute on the page element to "facets". In
the info element, add this:

  <facet:match key="all-pages"/>

Then in each topic, add this:

  <facet:match key="all-pages" value="something"/>

The value doesn't really matter. You're not doing anything
besides aggregating pages with that tag. All that matters is
that the key attribute matches on all pages.

This solves problems 2 and 3 above (which are symptoms of the
same problem). You'll still have to manually add a facet tag
to each page. Perhaps we could add a way for facets pages to
aggregate all pages. (By just omitting facet:match perhaps?)

And the big caveat. This is still experimental. There could
be backwards-incompatible changes before it's releases. But
what I outlined does actually work in Yelp 3 right now.

> Is there perhaps some sort of style="no-see-also" attribute possible
> that one can use to suppress these see-also and hierarchical links to
> the index?

That's come up a few times. It's pretty clear there's a need
to be able to specify one-way links. Definitely something that
should be on the table for Mallard 1.1.

--
Shaun




From philip.chimento at gmail.com  Wed May  4 13:49:33 2011
From: philip.chimento at gmail.com (Philip Chimento)
Date: Wed, 4 May 2011 19:49:33 +0200
Subject: Index of all topics in a set of Mallard pages
In-Reply-To: <1304285103.2137.253.camel@recto>
References: <BANLkTikaLxVmzsapS1SA7gks_faL_LDmNA@mail.gmail.com>
	 <1304285103.2137.253.camel@recto>
Message-ID: <BANLkTi=g9-dp4t6W=tDtjucCUuFXLH=2sg@mail.gmail.com>

2011/5/1 Shaun McCance <shaunm at gnome.org>:
> On Sun, 2011-05-01 at 21:30 +0200, Philip Chimento wrote:
>> Hi,
>>
>> Is there any facility in Mallard for creating an alphabetical index of
>> topics, even ones that are not linked to on the main 'index.page'
>> guide page?
>>
>> What I tried is to create a section on the main index.page:
>>
>> <section id="full-index">
>> ? <title>Index</title>
>> </section>
>>
>> and then a separate guide page, full-index.page, which every topic
>> page links to using something like:
>>
>> <link type="guide" xref="full-index"/>
>>
>> This works fairly well, except for three things:
>> - You have to manually add a link on every topic page.
>> - When viewing with Yelp, where each page normally shows its hierarchy
>> at the top, (e.g. Foo Guide -> ?Foo Topic) it now also shows a second
>> entry (Foo Guide -> ?Index -> ?Index of all help topics).
>> - There is a see-also link on the bottom of every topic page that
>> points to the index.
>
> You could try using the experimental facets extension.
>
> http://blogs.gnome.org/shaunm/2010/12/16/more-faceted-navigation/
> http://projectmallard.org/facet/1.0/
>
> Here's the gist. Create a page that collects all the links.
> Set the type attribute on the page element to "facets". In
> the info element, add this:
>
> ?<facet:match key="all-pages"/>
>
> Then in each topic, add this:
>
> ?<facet:match key="all-pages" value="something"/>
>
> The value doesn't really matter. You're not doing anything
> besides aggregating pages with that tag. All that matters is
> that the key attribute matches on all pages.
>
> This solves problems 2 and 3 above (which are symptoms of the
> same problem). You'll still have to manually add a facet tag
> to each page. Perhaps we could add a way for facets pages to
> aggregate all pages. (By just omitting facet:match perhaps?)
>
> And the big caveat. This is still experimental. There could
> be backwards-incompatible changes before it's releases. But
> what I outlined does actually work in Yelp 3 right now.

Hmm, I can't get it to work in Yelp 3.0.2. No links are showing up on
the index page. Have I got the correct namespace for 'facet'? I have
"http://projectmallard.org/facet/1.0/". I've tried with the
<facet:match> element inside and outside the pages' <info> elements,
if that makes any difference. Any ideas?
-- 
Philip


From shaunm at gnome.org  Wed May  4 16:12:41 2011
From: shaunm at gnome.org (Shaun McCance)
Date: Wed, 04 May 2011 16:12:41 -0400
Subject: Index of all topics in a set of Mallard pages
In-Reply-To: <BANLkTi=g9-dp4t6W=tDtjucCUuFXLH=2sg@mail.gmail.com>
References: <BANLkTikaLxVmzsapS1SA7gks_faL_LDmNA@mail.gmail.com>
	 <1304285103.2137.253.camel@recto>
	 <BANLkTi=g9-dp4t6W=tDtjucCUuFXLH=2sg@mail.gmail.com>
Message-ID: <1304539961.2137.329.camel@recto>

On Wed, 2011-05-04 at 19:49 +0200, Philip Chimento wrote:
> 2011/5/1 Shaun McCance <shaunm at gnome.org>:
> > On Sun, 2011-05-01 at 21:30 +0200, Philip Chimento wrote:
> >> Hi,
> >>
> >> Is there any facility in Mallard for creating an alphabetical index of
> >> topics, even ones that are not linked to on the main 'index.page'
> >> guide page?
> >>
> >> What I tried is to create a section on the main index.page:
> >>
> >> <section id="full-index">
> >>   <title>Index</title>
> >> </section>
> >>
> >> and then a separate guide page, full-index.page, which every topic
> >> page links to using something like:
> >>
> >> <link type="guide" xref="full-index"/>
> >>
> >> This works fairly well, except for three things:
> >> - You have to manually add a link on every topic page.
> >> - When viewing with Yelp, where each page normally shows its hierarchy
> >> at the top, (e.g. Foo Guide ->  Foo Topic) it now also shows a second
> >> entry (Foo Guide ->  Index ->  Index of all help topics).
> >> - There is a see-also link on the bottom of every topic page that
> >> points to the index.
> >
> > You could try using the experimental facets extension.
> >
> > http://blogs.gnome.org/shaunm/2010/12/16/more-faceted-navigation/
> > http://projectmallard.org/facet/1.0/
> >
> > Here's the gist. Create a page that collects all the links.
> > Set the type attribute on the page element to "facets". In
> > the info element, add this:
> >
> >  <facet:match key="all-pages"/>
> >
> > Then in each topic, add this:
> >
> >  <facet:match key="all-pages" value="something"/>
> >
> > The value doesn't really matter. You're not doing anything
> > besides aggregating pages with that tag. All that matters is
> > that the key attribute matches on all pages.
> >
> > This solves problems 2 and 3 above (which are symptoms of the
> > same problem). You'll still have to manually add a facet tag
> > to each page. Perhaps we could add a way for facets pages to
> > aggregate all pages. (By just omitting facet:match perhaps?)
> >
> > And the big caveat. This is still experimental. There could
> > be backwards-incompatible changes before it's releases. But
> > what I outlined does actually work in Yelp 3 right now.
> 
> Hmm, I can't get it to work in Yelp 3.0.2. No links are showing up on
> the index page. Have I got the correct namespace for 'facet'? I have
> "http://projectmallard.org/facet/1.0/". I've tried with the
> <facet:match> element inside and outside the pages' <info> elements,
> if that makes any difference. Any ideas?

1) On the page you want the links to appear on, make sure
you set the type attribute to "facets".

2) There was a typo in my instructions above. The page that
has the links has the facet:match element in the info element,
as above. The other pages, though, have a facet:tag element,
not a facet:match element. Add this to each page:

  <facet:tag key="all-pages" value="something"/>

Sorry. That's what happens when I don't proofread.

--
Shaun







From jeremy at bicha.net  Thu May  5 01:16:41 2011
From: jeremy at bicha.net (Jeremy Bicha)
Date: Thu, 05 May 2011 01:16:41 -0400
Subject: Citations
Message-ID: <4DC232B9.7090609@bicha.net>

Hi, I've been helping out the Ubuntu Documentation Team get our version
of the Gnome user guide into shape for the 11.04 release. I intend to
help Gnome out directly with docs too as time and priorities allow now
that 11.04 is basically done.

I probably would have posted to this list sooner because j1mc said that
he had posted something about citations to the Mallard discussion list
but when I checked this list's archives, I didn't see anything posted
since December and didn't even bother subscribing to the list.
Hopefully, shaun will be able to get the archives working again this
week, but it's hard to fix a problem you don't even know about.

So I'm going to be "that guy" who jumps into the conversation without
any clue about what's been said already.


j1mc and I were talking about citing AskUbuntu. While it basically falls
under the same license as the Gnome and Ubuntu docs, the site founder
requires very specific attribution[1] which I don't think is well suited
to the way our user docs work (but that's a different conversation). A
bigger issue is that it doesn't look like Mallard has sufficient
attribution support.

There are two already existing tags that could do this, <comment> and
<credit> but credit seems like the better choice to me. I suggest adding
a minimum of <link> and <title> to credit and maybe even <p>'s.

By the way, I was able to stuff a link in <email> without validation
failing so maybe the schema needs to sniff for basic email syntax there.

And the other issue is that Yelp doesn't expose any of this info to end
users who want to see it, even in the "editor-mode" that is not an
editor. I think there needs to be a balance with cluttering the help but
I don't believe we're really meeting the basic attribution requirements
of CC-BY-SA either.

[1] http://blog.stackoverflow.com/2009/06/attribution-required/

Jeremy Bicha

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 900 bytes
Desc: OpenPGP digital signature
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20110505/78434f6e/attachment.sig>

From jeremy at bicha.net  Thu May  5 01:17:41 2011
From: jeremy at bicha.net (Jeremy Bicha)
Date: Thu, 05 May 2011 01:17:41 -0400
Subject: Links
Message-ID: <4DC232F5.1080407@bicha.net>

http://projectmallard.org/1.0/mal_links.html talks about <links> but
that syntax doesn't work; I believe it ought to just be <link>. Same
thing for <groups> on that page.

Similar issues may be elsewhere in the documentation too.

Jeremy Bicha


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 900 bytes
Desc: OpenPGP digital signature
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20110505/e9103dbb/attachment.sig>

From shaunm at gnome.org  Thu May  5 09:30:37 2011
From: shaunm at gnome.org (Shaun McCance)
Date: Thu, 05 May 2011 09:30:37 -0400
Subject: Links
In-Reply-To: <4DC232F5.1080407@bicha.net>
References: <4DC232F5.1080407@bicha.net>
Message-ID: <1304602237.2137.333.camel@recto>

On Thu, 2011-05-05 at 01:17 -0400, Jeremy Bicha wrote:
> http://projectmallard.org/1.0/mal_links.html talks about <links> but
> that syntax doesn't work; I believe it ought to just be <link>. Same
> thing for <groups> on that page.

Doesn't work where? The links element was added fairly recently.
If you're using Yelp 2, it won't work.

But it is correct, and it does work. You're even using the links
element with the groups attribute on the front page of the Ubuntu
help:

http://bazaar.launchpad.net/~ubuntu-core-doc/gnome-user-docs/natty/view/head:/gnome-help/C/index.page

What are you using to build/view your Mallard help?

--
Shaun




From shaunm at gnome.org  Thu May 26 20:35:39 2011
From: shaunm at gnome.org (Shaun McCance)
Date: Thu, 26 May 2011 20:35:39 -0400
Subject: Citations
In-Reply-To: <4DC232B9.7090609@bicha.net>
References: <4DC232B9.7090609@bicha.net>
Message-ID: <1306456539.2142.373.camel@recto>

On Thu, 2011-05-05 at 01:16 -0400, Jeremy Bicha wrote:
> j1mc and I were talking about citing AskUbuntu. While it basically falls
> under the same license as the Gnome and Ubuntu docs, the site founder
> requires very specific attribution[1] which I don't think is well suited
> to the way our user docs work (but that's a different conversation). A
> bigger issue is that it doesn't look like Mallard has sufficient
> attribution support.
> 
> There are two already existing tags that could do this, <comment> and
> <credit> but credit seems like the better choice to me. I suggest adding
> a minimum of <link> and <title> to credit and maybe even <p>'s.

So I've been thinking about this quite a bit. Jim and I had
talked about the same thing on IRC before. We can certainly
discuss adding things to the content model of credit, but I
don't think it solves your immediate problem.

The credit element is informational. There's no requirements
on display. I don't want to start requiring that. I'm not
opposed to displaying credits in Yelp. I'm just opposed to
specifying that credits must be displayed. And if you need
to comply with a license, you need required behavior.

The comment element isn't right. It's for writers and editors
to leave notes for each other. The user never sees comments.

A note style could work. We wouldn't even have to put that in
the specification. (At least as a requirement. The spec does
*recommend* some note styles now.) But I think the most common
place to put legal mumbo-jumbo like this is at the bottom of
the page. And you can't put blocks down there if you've got
sections. I'd want to see these at the very very bottom, even
below automatic links. We don't have an element that can do
that right now.

What I'd proposed to Jim a while back is allowing the cite
element at the bottom of the page. This could work, but I've
thought of something I like better.

I propose we add a new element, colophon. It would be a formal
element: title (optional) and block content. It would only be
allowed as the last child of page. (Should we allow multiple?)
Its purpose is to hold text that should be displayed but which
is really not part of the main flow.

This is more general-purpose than a specialized element that is
strictly for citations. You might use it for feedback links. Or
thanks to your mom for all her support. Or pictures of kittens.
I don't know. Kittens are cute though.

Is the name "colophon" right? I think it's semantically right.
It serves the same purpose as a colophon in a book. It could be
confusing to people coming from DocBook, because the colophon
element in DocBook is "bigger", on par with chapters, whereas
this would be a small block container, on par with notes.

> By the way, I was able to stuff a link in <email> without validation
> failing so maybe the schema needs to sniff for basic email syntax there.

That might be worthwhile in a secondary Schematron rule. Mallard
intentionally allows all inline elements in any inline context.
It's important for internationalization. There could be a sort
of restricted inline set that doesn't include e.g. link. There's
always a trade-off between strictness and readability in schemas.
I erred on the side of readability.

Although email addresses are arguably no more text content than
URLs, and maybe credit emails should have just been attributes.
(I actually think they were in a very early version.)

(Personally, I tend to view the contents of credit as pseudo-RDF.
It allows external elements, and I generally recommend using that
in an RDF-like way.)

> And the other issue is that Yelp doesn't expose any of this info to end
> users who want to see it, even in the "editor-mode" that is not an
> editor. I think there needs to be a balance with cluttering the help but
> I don't believe we're really meeting the basic attribution requirements
> of CC-BY-SA either.
> 
> [1] http://blog.stackoverflow.com/2009/06/attribution-required/

As a side note, I think this is a really bad requirement on
how attribution should be provided. They can't retroactively
enforce this on any content added on their site before the
blog post was published. That's up to the contributors.

More importantly, the requirements are pretty hefty. They
remind me of the advertising clause in the old BSD license.
It's not so bad when you're just republishing near-verbatim
copy from one site. But imagine if you were remixing content
from 20 different sites, by 100 different authors, and they
all had this kind of attribution requirement. Your document
would have more attribution than content.

--
Shaun




From jwcampbell at gmail.com  Thu May 12 21:11:45 2011
From: jwcampbell at gmail.com (Jim Campbell)
Date: Fri, 13 May 2011 03:11:45 +0200
Subject: Attributions
In-Reply-To: <1303436762.2137.76.camel@recto>
References: <BANLkTim18otkvnb5rQqomv86BzGThpmQ=A@mail.gmail.com>
	 <1303436762.2137.76.camel@recto>
Message-ID: <BANLkTinWt8WiU8d6xCbh1tfE3Qy2sPA7Ew@mail.gmail.com>

Hi all,

On Thu, Apr 21, 2011 at 8:46 PM, Shaun McCance <shaunm at gnome.org> wrote:

>
> Maybe this is over-engineering. Maybe a common style
> hint on <note> is all we need. But CC and copyleft and
> attribution are important. I don't mind Mallard leaning
> a little more strongly towards open collaboration.
>
>
To me, a common style hint on note (ala <note style="attribution">) would
suffice, I think.

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20110513/184b8dfa/attachment.html>

From jwcampbell at gmail.com  Thu May 12 21:14:47 2011
From: jwcampbell at gmail.com (Jim Campbell)
Date: Fri, 13 May 2011 03:14:47 +0200
Subject: Faceted Navigation
In-Reply-To: <1292523967.15240.47.camel@recto>
References: <1292523967.15240.47.camel@recto>
Message-ID: <BANLkTikU-4EPdhzu_w3Ra=soGVQHM1UkEg@mail.gmail.com>

Hi All,

I agree with Phil in that it looks pretty cool.  I will express my thoughts
/ concerns below.

On Thu, Dec 16, 2010 at 12:26 PM, Shaun McCance <shaunm at gnome.org> wrote:

> Hi folks,
>
> I just blogged about an experiment I did to have faceted
> navigation in Mallard:
>
> http://blogs.gnome.org/shaunm/2010/12/16/more-faceted-navigation/
>


>
> The blog post is just a demo, and is short on markup details
> and other technical stuff. I want to lay out how I marked this
> all up and how it works, and put out some questions.
>
> This is all done with extension elements. There are two aspects
> to the extension: tagging pages, and collecting tagged pages.
> I think the tagging aspect can be reused for other extensions
> or features.
>
> Pages can include tags with the facet:tag element, inside the
> info element. This takes two attributes: key and values. So in
> the example on my blog, Message Board has this:
>
> <facet:tag key="lang" values="c"/>
> <facet:tag key="tech" values="webkit"/>
>
> Think of each facet:tag as a categorized set of tags. The values
> attribute can take a space-separated list. For example, if there
> were a demo that mixed C and Python, it might have:
>
> <facet:tag key="lang" values="c py"/>
>
> Tags have no inherent meaning, and their values are intended to
> be non-translatable identifiers, not human-readable strings. You
> can tag away using whatever tag keys you want, and possibly build
> other tools that do different things with some of your tags.
>
> Oh, and just like with links, you can tag sections as well.
>
>
This may just be an implementation detail, but in the video example on your
website, the Python and Javascript section headers still appear, even though
the user (you) have un-marked the Python and Javascript selections. There
may be some times when an entire section Is not relevant, and should be
removed/hiddent. Is it not possible to have the un-marked sections
disappear, or is that just not implemented in your example?


> Then there's the facets pages. These are special pages that have
> the type attribute set to "facets". I'll say "facets node" to
> mean either a facets page or a section within a facets page. A
> facets node can have facet:match and facet:choice elements in
> its info element.
>

> The facet:match element specifies which pages or sections should
> be linked to. To match nodes that specify a tag, regardless of its
> content, use it with just the key attribute:
>
> <facet:match key="lang"/>
>
> To match nodes with particular values for a tag, use both a key and
> a values attribute:
>
> <facet:match key="lang" values="c"/>
>
> The values attribute is again a space-separated list. It matches a
> node if it shares any values with the list in that node's tag. That
> is, these two match:
>
> <facet:match key="lang" values="c py"/>
> <facet:tag key="lang" values="vala py"/>
>
> Because they have an overlapping element ("py"). A facets node shows
> a link to a target node iff:
>
>  * All of the facets node's facet:match elements match the target
>   node's tags.
>  * And the target node is not linked to by a descendant node of the
>   facets node.
>
> Explanation on the second part: In my blog, the page matches anything
> that has the "lang" tag set. Each section then matches particular values
> of the "lang" tag. Skeleton markup:
>
> <page type="facets" id="facets">
>  <info>
>    <facet:match key="lang"/>
>  </info>
>  <title>Facets!</title>
>  <section id="c">
>    <info>
>      <facet:match key="lang" values="c"/>
>    </info>
>    <title>C</title>
>  </section>
>  <section id="py">
>    <info>
>      <facet:match key="lang" values="py"/>
>    </info>
>    <title>Python</title>
>  </section>
> </page>
>
> The second bullet point allows you to chunk things into sections based
> on the facet tags and not have them all also appear at the top.
>
> Then we have the selection mechanism. A facets node can have any number
> (including 0) of facet:choice elements. These have a leading facet:title
> element followed by one or more facet:case elements. Example:
>
> <facet:choice key="tech">
>  <facet:title>Technology</facet:title>
>  <facet:case values="gtk">GTK+</facet:case>
>  <facet:case values="gstreamer">GStreamer</facet:case>
> </facet:choice>
>
> This says to create a control to allow you to filter based on the "tech"
> facet tag. Human-readable text is given here. (Remember the tags are not
> intended to be human-readable.) And again, values can be a list. A case
> matches a target node if there's an overlap in values, just like match.
>
> Facets nodes can have any number of facet:choice elements. Facet choices
> affect all facet links in the facets node, including those in descendant
> facets nodes. A choice is true for a link of any of the active cases in
> the choice matches the target node. A link is displayed if every choice
> in context (including those in ancestor nodes) is true for it.
>

In the example that you provide on your blog, the facet selection mechanism
has the facet options printed at the top of the page. I would be concerned
that the page could get overloaded with facets if they are used
extensively.  For example, consider additional facets such as experience
level, platform, etc.

Is that concern unfounded?  Would all facets available in a documentation
set appear in the "facets" section at the top of each face page, or would
only the facets that are relevant for that particular page (or set of pages)
appear?



>
> Sheesh, sorry for the specification-like language. Open questions:
>
> * There's no way to AND on cases or matches. For example, if I were to
> change the Message Board example to have this:
>
> <facet:tag key="tech" values="gtk webkit"/>
>
> It would be displayed if you have either GTK+ or WebKit checked. Is it
> useful to be able to display links only if all their tag values match?
>
> * There's only one type of selector here: non-exclusive multiple choice.
> I could imagine others. Exclusive multiple choice (i.e. radio buttons).
> Numeric ranges. On/off toggles (you might think you can do that with a
> single case in a choice, but it's different). What do we need? Probably
> we can just start with this and grow from it as needs arise.
>
> I'd like to hear comments, suggestions, and questions. What I've done
> so far has worked really well, and I didn't hit any walls in the core
> language that prevented me from doing the extension (which is good).
> I think this is useful for "cookbook" documents. I wonder if others
> have other uses for it.
>
> Thanks,
> Shaun McCance
> Community Help Expert
> http://syllogist.net/
>
>
>
First, let me say that, though I've read the I am wondering if it may be
cleaner to have the facets:choices (if I'm understanding it correctly)
configured outside of the actual page file (as its own file, perhaps called
facets.config), rather than within the page file.  If it is in the page
file, I think we'd run into a heap of options that are required in the top
of a page file, and it could get (1) pretty messy and (2) difficult to
maintain.

As a comparison, I'm thinking of the differences between embedded CSS (with
all of the page's CSS options at the top of the HTML document) as compared
to external CSS (where all of the CSS is handled in one separate file).

Perhaps these user options could sit in the yelp configuration file in the
user's home directory.

Here are a couple of links that I found that might be helpful:
http://www.sagehill.net/docbookxsl/Profiling.html
http://docs.oasis-open.org/dita/v1.1/OS/archspec/condproc.html

<http://docs.oasis-open.org/dita/v1.1/OS/archspec/condproc.html>Jim

P.S. This email was sitting in my 'drafts' directory for several months,
apparently.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20110513/d90e8de1/attachment.html>