Re: Some preliminaries and questions about lingo, etcetera.

On Mar 26, 2012, at 10:21 PM, Grant Robertson wrote:

> Before I can start writing, I need to have a full understanding of how the
> spec works. I have done quite a lot of studying of the old specification. In
> fact, I came to this "job" because I had some pretty detailed questions to
> ask and so tried to join the mailing list (the now-dead list indicated in
> the old spec) and ran into some "difficulty." I have now also read through
> the new Core 1.1 spec pretty closely. In order to amass my full
> understanding I will need to essentially rewrite major sections of the spec
> in my own words. Because RDFa is such an odd combination of simple and
> complex, I will also need to make several diagrams to help me map out the
> whole thing in my head. This is the way I learn. It is also how I came to
> technical writing. Fortunately, these documents will also come in handy as
> additional supporting documentation. Keep in mind: I have no intention of
> these documents ever replacing or becoming part of the specifications. They
> are merely to aid myself and any lay readers in understanding said
> specification. 
> 
> So, even though the end goal is to write some rather simple documents for
> lay readers, I must first ask a lot of really technical questions and write
> up a complete description of the processing rules. In order to make this
> whole questioning process go a lot easier, I hope to use a consistent means
> of indicating various things in my writing or examples. To that end, I would
> like to ask:
> 
> (A) Do you have an abbreviated way to say that an attribute exists? For
> instance, I was thinking of putting the attribute name in curly braces to
> indicate that an attribute exists. 
> 
> {@about}
> 
> ... would indicate that the @about attribute is present within the current
> evaluation context. So...
> 
> !{@about} 
> 
> ... Would naturally indicate that the @about attribute is NOT present within
> the current evaluation context.
> 
> Sure, I could use a pretend function call, but I want these things to be as
> compact as possible so I can fit them into diagrams easily. 

This seems about as good a mechanism as any, but if there are conventions typically used in other documents (e.g. HTML5), we might want to stick with those. Also, see below.

> (B) Do you have a preferred form of writing boolean logic expressions, or
> can I just use my own pseudo-code based on Java syntax?

Perhaps some examples would be in order; most readers likely have some familiarity with JavaScript; I'd stick with a reasonably common subset of C-type languages.

W3C mostly uses EBNF for grammar, which may be appropriate for what you want to do, depending on the level of formality you're looking for.

> (C) Do you have a preferred document format? Plain HTML? Libre Office?
> DocBook?

Specs are written in HTML with ReSpec.js [1], this provides a lot of aide in normalized references, creating indexes, and internal references. ReSpec2.js [2] has even more flexibility, and we should probably eventually be moving to this.

> (D) What is the best format to present diagrams to the group for review?
> Just attach them to an e-mail posted to the list? Is there a site where they
> should be uploaded? 

At this point, I'd say whatever format is easiest for you. There is a Wiki [3], which is used for things that might be more complex than a simple email. Note that W3C reflector email isn't kind to rich markup, and I'm not sure what it would do with an attached image.

> (E) Do you have a standardized way of indicating that something is a
> "variable" within your processing sequence? In the old spec it seemed that
> you used square brackets around "variable" names. This does not seem to be
> the norm within the new documentation. Is it OK if I stick with the old
> method for my questions, to add clarity while reducing the verbosity of the
> questions?

In my uses, I italisize variable names with <em></em>. Depending on what you're doing, it may make sense to use ReSpec tref/tdef or similar, to identify variables, as this allows for CSS markup, and can tie usage to definition. ReSpec2 has more direct support for this, otherwise it's often done with inline function definitions (see RDFa Core 1.1 source, for example [4]). ReSpec supports <dfn>, which might be useful.

I used ReSpec2 extensively in a previous project, and I'd be happy to help get you going with such an environment.

> (F) Are there any other conventions that you use within the mailing list to
> aid in brevity and clarity?

The mailing list has automatic support for referencing issues, I believe by referencing the issue number in the subject; this can be useful.

Gregg

[1] http://dev.w3.org/2009/dap/ReSpec.js/documentation.html
[2] http://dvcs.w3.org/hg/respec2
[3] http://www.w3.org/2010/02/rdfa/wiki/Main_Page
[4] http://www.w3.org/2010/02/rdfa/sources/rdfa-core/Overview-src.html

Received on Tuesday, 27 March 2012 18:56:34 UTC