[whatwg] Spec formats

[Perry Smith]

On Mar 23, 2010, at 1:11 AM, Ian Hickson wrote:

> On Mon, 22 Mar 2010, Perry Smith wrote:
>> On Mar 22, 2010, at 7:00 PM, Ian Hickson wrote:
>>>
>>> If you would like to generate ePub or other formats of the spec, I
>>> would be happy to coordinate with you to set up a system that can do
>>> this on a regular basis for the spec, just like the PDF and  
>>> multipage
>>> versions of the spec get regularly generated each day or with each
>>> update.
>>
>> I would like to help with this.
>>
>> I downloaded the source you pointed me to.  Are the post processing
>> tools available?
>>
>> The ePub generators all start with HTML.
>
> What the best way to do this is depends on what exactly the  
> generators do.

I hope you are patient with me.  Its clear that I'm not up to speed on  
all the different versions and features of these specs or even how  
many specs there are.

I think its best to think of ePub format as being similar to PDF or  
printed copy.  The typical reader device does not have a mouse.  It is  
possible to tab through links and press "open" to go, for example,  
from an entry in the table of contents to the entry itself.  But the  
UI is very crude and the devices are very slow.  To start, I'd like to  
do something pretty simple.  Eventually, if plausible, it would be  
nice to have a way for the user pick which features he wants and have  
a "custome" html file downloaded to them which they can feed to their  
ePub generator.  We can have pre-made ePub versions too which would be  
whatever options we decide to have.

For me, there are two modes when I read one of these specifications.   
One is I am writing and debugging code (as an "author" in this case).   
In that mode, I am constantly opening new windows and doing all manner  
of searches to try and understand a particular part.  An eBook is not  
going to work for this mode at all.

The other mode is when I want to sit down under a shade tree and  
really read an entire section.  That is the place where an eBook  
works.  I think keeping this use in mind will help us determine what  
to keep and what to leave out.

> Do you need the files with or without the section numbering and
> cross-references, for example?

Yes.  I think we want cross-references.  The generators understand  
HTML so they will auto number a <ol>.  I'm not sure what the source  
has (yet) so as far as "section numbering", I am not sure how to  
answer that question yet.  I would assume we want the same as what the  
single page versions have.

> Do you want the JavaScript that does the
> reverse cross-referencing of <dfn> elements?

These are super cool but I don't see how that would work in an eBook.   
I don't think they have the concept of a pop up window.  For now, lets  
leave these out.

> How about the alternative
> style sheets for authors, and the UI to support them?

I'm not 100% sure I know what you are referring to.  I see a radio  
button for "Hide UA text".  Is that for authors?

>
> Also, which specs do you want to generate?  The most useful spec to
> generate might be the complete.html file, since it's essentially a
> superset of all the others, but we might also want to just do the  
> WHATWG
> HTML spec (i.e. HTML5), which would be shorter.

Yes.  Lets do the complete html file first.  As I mentioned above, I'm  
hoping that we can allow users to customize it later on.  I'm sure  
there will be users that want only the "official" or final version of  
the w3.com version of each spec(s).

>
>> There will also need to be some style sheet tweaking because  
>> usually the
>> readers are black and white.
>
> There are a number of style sheets involved in the current scheme,  
> but we
> can probably come up with some set of overrides to make the ePub copy
> suitably black and white.
>
>
>> On a slightly different topic, is there an official "cover" for this
>> book (or these books)?
>
> Not currently, but I'm sure we can figure something out. What should  
> it
> look like?

A .png file.  These can be simple like "HTML 5" put into Photoshop and  
let it spit out a png file.  I can do this as we work through this.  I  
just wanted to ask to make sure.  We might get some volunteers to  
create nifty book covers (hint hint).

> The way the multipage version is generated currently is that I have a
> script that generates an HTML file, and when it's ready, I do an HTTP
> request to a service Philip maintains. That service then processes the
> HTML file appropriately and sends back a tarball with the multipage
> version all ready to be expanded. If we can set up something  
> similar, that
> would be awesome.

Yes.  I think I'm hoping for something a bit more eventually.  I'd  
like eventually to offer a service where users and pick various  
features and get back either an html file, or maybe a final ePub  
file.  The reason I'm leaning this way is because the readers seem so  
limited -- given the users exactly what they want seems more important  
in this format than in a web environment.

>
> If you'd like to coordinate this by IRC instead, which can be easier,
> the #whatwg channel on Freenode is the place to find me (Hixie).

Lets keep it with email for now.  This is a background task for me and  
email allows me to process things when I have time.

Thanks,
Perry