[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Public WebGL] WebGL Reference Pages



On Mon, Aug 13, 2012 at 3:55 PM, Benoit Jacob <bjacob@mozilla.com> wrote:
>
>
> ----- Original Message -----
>>
>> On Mon, Aug 13, 2012 at 11:19 AM, Gregg Tavares (社用)
>> <gman@google.com> wrote:
>> >
>> >
>> >
>> > On Mon, Aug 13, 2012 at 10:59 AM, Mark Callow
>> > <callow_mark@hicorp.co.jp>
>> > wrote:
>> >>
>> >> On 12/08/07 18:44, Gregg Tavares (社用) wrote:
>> >>
>> >>
>> >> On Tue, Aug 7, 2012 at 6:25 PM, Benoit Jacob <bjacob@mozilla.com>
>> >> wrote:
>> >>>
>> >>>
>> >>> Is it acceptable to copy text from other Khronos resources, such
>> >>> as:
>> >>>
>> >>>  - OpenGL ES man pages
>> >>>  - OpenGL ES sprc
>> >>>  - WebGL spec
>> >>
>> >>
>> >> I don't know if it is acceptable copy from the OpenGL ES spec or
>> >> man
>> >> pages. Honestly those pages often seem derived from OpenGL 1.0 and
>> >> it would
>> >> be nice, where appropriate, to just write new docs.
>> >>
>> >> I don't know about the legal position either but I worry about
>> >> duplication
>> >> of effort and divergence between the OpenGL ES and WebGL man
>> >> pages. The vast
>> >> majority of the information is the same for both. It would be nice
>> >> to have
>> >> at least the source in one place with page sections noting
>> >> differences in
>> >> WebGL where necessary.
>> >>
>> >> I also worry that using a Wiki for the reference pages creates an
>> >> enormous
>> >> amount of manual effort that could otherwise be automated such as
>> >> making
>> >> live references from one page to another.
>> >
>> >
>> > I totally agree with you. As an engineer I want shared docs,
>> > automated code
>> > snippets, docs generated from IDLs. etc, etc etc.
>> >
>> >  But as a counter example, look how long the GL pages have had bad
>> >  info. I
>> > filed bugs. They still aren't fixed. If they were a wiki I'd have
>> > fixed them
>> > myself. As something checked in somewhere I have no idea where they
>> > are or
>> > how to get access to their repo or if I'm even allowed to access
>> > that repo.
>> > I'm lucky I even had an idea where to file bugs. On a Wiki I just
>> > click
>> > [EDIT] and fix it.
>>
>> The transition of the WebGL repo to Github should make incorporation
>> of changes like this much easier and mostly automated. Would it be
>> feasible to check in the sources to the reference pages, and
>> postprocess them to generate wiki pages or HTML? I know there's
>> already been discussion about the lower barrier to entry with a wiki,
>> but the lack of automated tools for management seems really
>> problematic in the long run.
>
> Again, I am not convinced that mediawiki really lacks such tools; one would need to be more specific here, to make progress. What's missing? If it's just "see also" lists, mediawiki does offer tools for that.

I apologize but I don't have concrete examples of missing
functionality. I can only say definitively from my experience that
doing markup on wiki pages by hand is tedious. David Sheets' work to
autogenerate the WebGL extension registry from XML files is a great
example of a massive productivity improvement. I can't imagine
maintaining the registry by hand any more. Similar productivity
increases could surely be achieved for the creation and maintenance of
WebGL reference pages by using some sort of template system rather
than writing wiki pages for each API call by hand.

-Ken


> Benoit
>
>
>>
>> -Ken
>>
>>
>> >>
>> >>
>> >> Regards
>> >>
>> >> -Mark
>> >>
>> >>
>> >> --
>> >> 注意:この電子メールには、株式会社エイチアイの機密情報が含まれている場合が有ります。正式なメール受信者では無い場合はメール複製、
>> >> 再配信または情報の使用を固く禁じております。エラー、手違いでこのメールを受け取られましたら削除を行い配信者にご連絡をお願いいたし
>> >> ます。
>> >>
>> >> NOTE: This electronic mail message may contain confidential and
>> >> privileged
>> >> information from HI Corporation. If you are not the intended
>> >> recipient, any
>> >> disclosure, photocopying, distribution or use of the contents of
>> >> the
>> >> received information is prohibited. If you have received this
>> >> e-mail in
>> >> error, please notify the sender immediately and permanently delete
>> >> this
>> >> message and all related copies.
>> >
>> >
>>
>> -----------------------------------------------------------
>> You are currently subscribed to public_webgl@khronos.org.
>> To unsubscribe, send an email to majordomo@khronos.org with
>> the following command in the body of your email:
>> unsubscribe public_webgl
>> -----------------------------------------------------------
>>
>>

-----------------------------------------------------------
You are currently subscribed to public_webgl@khronos.org.
To unsubscribe, send an email to majordomo@khronos.org with
the following command in the body of your email:
unsubscribe public_webgl
-----------------------------------------------------------