Re: Some preliminaries and questions about lingo, etcetera.

Grant,

I think we should go for HTML. If any of these documents are published under a W3C banner, than that is a requirement; if the documents are simply published on rdfa.info, then of course there is no such requirement, but my choice would still be HTML. 

For the diagram formats: in an ideal world I would use SVG and embed it into the document. However, when I did that in the RDFa Primer, the experience was awful, because the browsers were just too slow. We are not yet there with SVG, unfortunately. What I plan to do with the primer is to put PNG images into the document, and link these to SVG if people want to use them.

Ivan



On Mar 27, 2012, at 07:21 , 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. 
> 
> 
> (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?
> 
> 


----
Ivan Herman, W3C Semantic Web Activity Lead
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
FOAF: http://www.ivan-herman.net/foaf.rdf