[webkit-dev] Some text about the B3 compiler

Fri Jan 29 11:38:56 PST 2016

I started coverting the documentation to Markdown.  I don’t think this is a good idea.

- Markdown has no definition lists.  The entire IR document is a definition list.  I don’t want B3’s documentation to be blocked on this issue.
- Markdown’s conversion step makes the workflow awkward.  I’m not going to use some Markdown editing app - that will prevent me from being able to properly format code examples.  I need a code editor for that.

I think that this documentation should be HTML.  I don’t think we should expend a lot of energy to formatting it nicely.  The point of this document is for it to be read by engineers while they hack code.

-Filip

> On Jan 29, 2016, at 10:12 AM, Timothy Hatcher <timothy at apple.com> wrote:
> 
> I also added:
> 
> https://webkit.org/documentation/b3/air/ <https://webkit.org/documentation/b3/air/> loads /docs/b3/assembly-intermediate-representation.md
> 
>> On Jan 29, 2016, at 10:05 AM, Filip Pizło <fpizlo at apple.com <mailto:fpizlo at apple.com>> wrote:
>> 
>> Thank you!  I'll convert them today. 
>> 
>> -Filip
>> 
>> On Jan 29, 2016, at 10:02 AM, Timothy Hatcher <timothy at apple.com <mailto:timothy at apple.com>> wrote:
>> 
>>> Markdown is pretty similar to the wiki formatting and very simple.
>>> 
>>> You can look at a cheatsheet if you login to the blog: https://webkit.org/wp/wp-admin/post.php?post=4300&action=edit <https://webkit.org/wp/wp-admin/post.php?post=4300&action=edit>
>>> 
>>> I have also used this HTML to Markdown converter before: http://domchristie.github.io/to-markdown/ <http://domchristie.github.io/to-markdown/>
>>> 
>>> The pages are created:
>>> 
>>> https://webkit.org/documentation/b3/ <https://webkit.org/documentation/b3/> loads /docs/b3/bare-bones-backend.md
>>> https://webkit.org/documentation/b3/intermediate-representation/ <https://webkit.org/documentation/b3/intermediate-representation/> loads /docs/b3/intermediate-representation.md
>>> 
>>> Once those files are added to SVN, they will get picked up by the site. I can change those to point to other names if you want something different.
>>> 
>>> — Timothy Hatcher
>>> 
>>>> On Jan 29, 2016, at 9:34 AM, saam barati <saambarati1 at gmail.com <mailto:saambarati1 at gmail.com>> wrote:
>>>> 
>>>> I'm happy to convert the document to markdown. Can you send me your latest revision or post it to the website?
>>>> 
>>>> I usually look at:
>>>> http://daringfireball.net/projects/markdown/syntax <http://daringfireball.net/projects/markdown/syntax>
>>>> For a refresher on the syntax.
>>>> 
>>>> Tim, could you create a page that loads the markdown file?
>>>> 
>>>> Thanks,
>>>> Saam
>>>> 
>>>> On Jan 29, 2016, at 12:06 AM, Filip Pizło <fpizlo at apple.com <mailto:fpizlo at apple.com>> wrote:
>>>> 
>>>>> I'm all for this but I don't know anything about markdown. 
>>>>> 
>>>>> What's the best way to proceed?
>>>>> 
>>>>> -Filip
>>>>> 
>>>>> On Jan 28, 2016, at 9:24 PM, Timothy Hatcher <timothy at apple.com <mailto:timothy at apple.com>> wrote:
>>>>> 
>>>>>> They should be markdown files like we do for the code style and policy documents.
>>>>>> 
>>>>>> https://trac.webkit.org/browser/trunk/Websites/webkit.org/code-style.md <https://trac.webkit.org/browser/trunk/Websites/webkit.org/code-style.md>
>>>>>> 
>>>>>> We can then make Wordpress pages on the site that load the markdown.
>>>>>> 
>>>>>> Maybe put them in a /docs/b3/ directory?
>>>>>> 
>>>>>> — Timothy Hatcher
>>>>>> 
>>>>>> On Jan 28, 2016, at 4:48 PM, Filip Pizlo <fpizlo at apple.com <mailto:fpizlo at apple.com>> wrote:
>>>>>> 
>>>>>>> I guess we could put it in Websites/webkit.org/b3 <http://webkit.org/b3>.  Then patches could edit both B3 and the documentation in one go, and the documentation would go live when it’s committed.
>>>>>>> 
>>>>>>> Does anyone object to this?
>>>>>>> 
>>>>>>> -Filip
>>>>>>> 
>>>>>>> 
>>>>>>>> On Jan 28, 2016, at 4:39 PM, Saam barati <sbarati at apple.com <mailto:sbarati at apple.com>> wrote:
>>>>>>>> 
>>>>>>>> Yeah. That’d be the easiest way to keep it up IMO.
>>>>>>>> 
>>>>>>>> Saam
>>>>>>>> 
>>>>>>>>> On Jan 28, 2016, at 4:37 PM, Filip Pizło <fpizlo at apple.com <mailto:fpizlo at apple.com>> wrote:
>>>>>>>>> 
>>>>>>>>> +1
>>>>>>>>> 
>>>>>>>>> Do you think we should move the documentation to a file in svn so that it can be reviewed as part of patch review?
>>>>>>>>> 
>>>>>>>>> -Filip
>>>>>>>>> 
>>>>>>>>> On Jan 28, 2016, at 4:32 PM, Saam barati <sbarati at apple.com <mailto:sbarati at apple.com>> wrote:
>>>>>>>>> 
>>>>>>>>>> This is great. Thanks Fil.
>>>>>>>>>> 
>>>>>>>>>> I propose that we do all that we can to keep this updated.
>>>>>>>>>> I suggest that all patches that change to the IR should also include with it 
>>>>>>>>>> a change to the documentation, and that reviewers should require this.
>>>>>>>>>> 
>>>>>>>>>> It’d also be great if other significant changes that seem like the deserve
>>>>>>>>>> a mention in the documentation also get added as part of patches.
>>>>>>>>>> 
>>>>>>>>>> Saam
>>>>>>>>>> 
>>>>>>>>>>> On Jan 28, 2016, at 4:23 PM, Filip Pizlo <fpizlo at apple.com <mailto:fpizlo at apple.com>> wrote:
>>>>>>>>>>> 
>>>>>>>>>>> Hi everyone,
>>>>>>>>>>> 
>>>>>>>>>>> We’ve been working on a new compiler backend for the FTL JIT, which we call B3.  It stands for “Bare Bones Backend”.  We recently enabled it on X86/Mac, and we’re working hard to enable it on other platforms.
>>>>>>>>>>> 
>>>>>>>>>>> If you’re interested in how it works, I’ve started writing documentation.  I’ll be adding more to it soon!
>>>>>>>>>>> https://trac.webkit.org/wiki/BareBonesBackend <https://trac.webkit.org/wiki/BareBonesBackend>
>>>>>>>>>>> https://trac.webkit.org/wiki/B3IntermediateRepresentation <https://trac.webkit.org/wiki/B3IntermediateRepresentation>
>>>>>>>>>>> 
>>>>>>>>>>> -Filip
>>>>>>>>>>> 
>>>>>>>>>>> _______________________________________________
>>>>>>>>>>> webkit-dev mailing list
>>>>>>>>>>> webkit-dev at lists.webkit.org <mailto:webkit-dev at lists.webkit.org>
>>>>>>>>>>> https://lists.webkit.org/mailman/listinfo/webkit-dev <https://lists.webkit.org/mailman/listinfo/webkit-dev>
>>>>>>>>>> 
>>>>>>>> 
>>>>>>> 
>>>>>>> _______________________________________________
>>>>>>> webkit-dev mailing list
>>>>>>> webkit-dev at lists.webkit.org <mailto:webkit-dev at lists.webkit.org>
>>>>>>> https://lists.webkit.org/mailman/listinfo/webkit-dev <https://lists.webkit.org/mailman/listinfo/webkit-dev>
>>>>> _______________________________________________
>>>>> webkit-dev mailing list
>>>>> webkit-dev at lists.webkit.org <mailto:webkit-dev at lists.webkit.org>
>>>>> https://lists.webkit.org/mailman/listinfo/webkit-dev <https://lists.webkit.org/mailman/listinfo/webkit-dev>
>>> 
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.webkit.org/pipermail/webkit-dev/attachments/20160129/9e7431c5/attachment.html>