Some preliminaries and questions about lingo, etcetera.

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. 


(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?

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

(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? 

(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?

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

Received on Tuesday, 27 March 2012 05:21:44 UTC