Hi All,<br><br>I agree with Phil in that it looks pretty cool. I will express my thoughts / concerns below. <br><br><div class="gmail_quote">On Thu, Dec 16, 2010 at 12:26 PM, Shaun McCance <span dir="ltr"><<a href="mailto:shaunm@gnome.org" target="_blank">shaunm@gnome.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0pt 0pt 0pt 0.8ex;border-left:1px solid rgb(204, 204, 204);padding-left:1ex">
Hi folks,<br>
<br>
I just blogged about an experiment I did to have faceted<br>
navigation in Mallard:<br>
<br>
<a href="http://blogs.gnome.org/shaunm/2010/12/16/more-faceted-navigation/" target="_blank">http://blogs.gnome.org/shaunm/2010/12/16/more-faceted-navigation/</a><br></blockquote><div> </div><blockquote class="gmail_quote" style="margin:0pt 0pt 0pt 0.8ex;border-left:1px solid rgb(204, 204, 204);padding-left:1ex">
<br>
The blog post is just a demo, and is short on markup details<br>
and other technical stuff. I want to lay out how I marked this<br>
all up and how it works, and put out some questions.<br>
<br>
This is all done with extension elements. There are two aspects<br>
to the extension: tagging pages, and collecting tagged pages.<br>
I think the tagging aspect can be reused for other extensions<br>
or features.<br>
<br>
Pages can include tags with the facet:tag element, inside the<br>
info element. This takes two attributes: key and values. So in<br>
the example on my blog, Message Board has this:<br>
<br>
<facet:tag key="lang" values="c"/><br>
<facet:tag key="tech" values="webkit"/><br>
<br>
Think of each facet:tag as a categorized set of tags. The values<br>
attribute can take a space-separated list. For example, if there<br>
were a demo that mixed C and Python, it might have:<br>
<br>
<facet:tag key="lang" values="c py"/><br>
<br>
Tags have no inherent meaning, and their values are intended to<br>
be non-translatable identifiers, not human-readable strings. You<br>
can tag away using whatever tag keys you want, and possibly build<br>
other tools that do different things with some of your tags.<br>
<br>
Oh, and just like with links, you can tag sections as well.<br>
<br></blockquote><div><br>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?<br>
</div><blockquote class="gmail_quote" style="margin:0pt 0pt 0pt 0.8ex;border-left:1px solid rgb(204, 204, 204);padding-left:1ex">
Then there's the facets pages. These are special pages that have<br>
the type attribute set to "facets". I'll say "facets node" to<br>
mean either a facets page or a section within a facets page. A<br>
facets node can have facet:match and facet:choice elements in<br>
its info element. <br></blockquote><blockquote class="gmail_quote" style="margin:0pt 0pt 0pt 0.8ex;border-left:1px solid rgb(204, 204, 204);padding-left:1ex">
<br>
The facet:match element specifies which pages or sections should<br>
be linked to. To match nodes that specify a tag, regardless of its<br>
content, use it with just the key attribute:<br>
<br>
<facet:match key="lang"/><br>
<br>
To match nodes with particular values for a tag, use both a key and<br>
a values attribute:<br>
<br>
<facet:match key="lang" values="c"/><br>
<br>
The values attribute is again a space-separated list. It matches a<br>
node if it shares any values with the list in that node's tag. That<br>
is, these two match:<br>
<br>
<facet:match key="lang" values="c py"/><br>
<facet:tag key="lang" values="vala py"/><br>
<br>
Because they have an overlapping element ("py"). A facets node shows<br>
a link to a target node iff:<br>
<br>
* All of the facets node's facet:match elements match the target<br>
node's tags.<br>
* And the target node is not linked to by a descendant node of the<br>
facets node.<br>
<br>
Explanation on the second part: In my blog, the page matches anything<br>
that has the "lang" tag set. Each section then matches particular values<br>
of the "lang" tag. Skeleton markup:<br>
<br>
<page type="facets" id="facets"><br>
<info><br>
<facet:match key="lang"/><br>
</info><br>
<title>Facets!</title><br>
<section id="c"><br>
<info><br>
<facet:match key="lang" values="c"/><br>
</info><br>
<title>C</title><br>
</section><br>
<section id="py"><br>
<info><br>
<facet:match key="lang" values="py"/><br>
</info><br>
<title>Python</title><br>
</section><br>
</page><br>
<br>
The second bullet point allows you to chunk things into sections based<br>
on the facet tags and not have them all also appear at the top.<br>
<br>
Then we have the selection mechanism. A facets node can have any number<br>
(including 0) of facet:choice elements. These have a leading facet:title<br>
element followed by one or more facet:case elements. Example:<br>
<br>
<facet:choice key="tech"><br>
<facet:title>Technology</facet:title><br>
<facet:case values="gtk">GTK+</facet:case><br>
<facet:case values="gstreamer">GStreamer</facet:case><br>
</facet:choice><br>
<br>
This says to create a control to allow you to filter based on the "tech"<br>
facet tag. Human-readable text is given here. (Remember the tags are not<br>
intended to be human-readable.) And again, values can be a list. A case<br>
matches a target node if there's an overlap in values, just like match.<br>
<br>
Facets nodes can have any number of facet:choice elements. Facet choices<br>
affect all facet links in the facets node, including those in descendant<br>
facets nodes. A choice is true for a link of any of the active cases in<br>
the choice matches the target node. A link is displayed if every choice<br>
in context (including those in ancestor nodes) is true for it.<br></blockquote><div><br>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.<br>
<br>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?<br><br> </div><blockquote class="gmail_quote" style="margin:0pt 0pt 0pt 0.8ex;border-left:1px solid rgb(204, 204, 204);padding-left:1ex">
<br>
Sheesh, sorry for the specification-like language. Open questions:<br>
<br>
* There's no way to AND on cases or matches. For example, if I were to<br>
change the Message Board example to have this:<br>
<br>
<facet:tag key="tech" values="gtk webkit"/><br>
<br>
It would be displayed if you have either GTK+ or WebKit checked. Is it<br>
useful to be able to display links only if all their tag values match?<br>
<br>
* There's only one type of selector here: non-exclusive multiple choice.<br>
I could imagine others. Exclusive multiple choice (i.e. radio buttons).<br>
Numeric ranges. On/off toggles (you might think you can do that with a<br>
single case in a choice, but it's different). What do we need? Probably<br>
we can just start with this and grow from it as needs arise.<br>
<br>
I'd like to hear comments, suggestions, and questions. What I've done<br>
so far has worked really well, and I didn't hit any walls in the core<br>
language that prevented me from doing the extension (which is good).<br>
I think this is useful for "cookbook" documents. I wonder if others<br>
have other uses for it.<br>
<br>
Thanks,<br>
Shaun McCance<br>
Community Help Expert<br>
<a href="http://syllogist.net/" target="_blank">http://syllogist.net/</a><br>
<br>
<br></blockquote><div><br>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. <br>
<br>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). <br>
<br>Perhaps these user options could sit in the yelp configuration file in the user's home directory.<br><br>Here are a couple of links that I found that might be helpful: <br><a href="http://www.sagehill.net/docbookxsl/Profiling.html" target="_blank">http://www.sagehill.net/docbookxsl/Profiling.html</a><br>
<a href="http://docs.oasis-open.org/dita/v1.1/OS/archspec/condproc.html" target="_blank">http://docs.oasis-open.org/dita/v1.1/OS/archspec/condproc.html</a></div><div><br></div><div><a href="http://docs.oasis-open.org/dita/v1.1/OS/archspec/condproc.html" target="_blank"></a>Jim</div>
<div><br></div><div>P.S. This email was sitting in my 'drafts' directory for several months, apparently.<br></div></div>