Follow up on this: > On Jan 29, 2016, at 11:38 AM, Filip Pizlo <fpi...@apple.com> wrote: > > 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.
It turns out that it does have them, but they are very weak. For example, you can’t have code blocks or paragraphs inside them. We want to have code blocks inside opcode definitions, to show examples. > - 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. This was hard to get around. This isn’t a problem with Markdown, but rather, a problem with using Wordpress to render Markdown that is in svn. There is no way to preview the Markdown before committing it. That would lead to unusual problems, where after a patch is landed, the patch author or someone else would have to do a bunch of blind follow-up commits to fix any style issues, like code blocks that don’t fit properly or whatever. Considering that we will have to be hacking raw HTML inside those Markdown files (due to definition lists), the lack of preview basically means that you have no way of predicting what the your HTML will render like. > > 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. I landed raw HTML documentation: http://trac.webkit.org/changeset/195841 <http://trac.webkit.org/changeset/195841> I filed this bug about improving its style: https://bugs.webkit.org/show_bug.cgi?id=153674 <https://bugs.webkit.org/show_bug.cgi?id=153674> -Filip > > -Filip > > >> On Jan 29, 2016, at 10:12 AM, Timothy Hatcher <timo...@apple.com >> <mailto:timo...@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 <fpi...@apple.com >>> <mailto:fpi...@apple.com>> wrote: >>> >>> Thank you! I'll convert them today. >>> >>> -Filip >>> >>> On Jan 29, 2016, at 10:02 AM, Timothy Hatcher <timo...@apple.com >>> <mailto:timo...@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 <saambara...@gmail.com >>>>> <mailto:saambara...@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 <fpi...@apple.com >>>>> <mailto:fpi...@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 <timo...@apple.com >>>>>> <mailto:timo...@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 <fpi...@apple.com >>>>>>> <mailto:fpi...@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 <sbar...@apple.com >>>>>>>>> <mailto:sbar...@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 <fpi...@apple.com >>>>>>>>>> <mailto:fpi...@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 <sbar...@apple.com >>>>>>>>>> <mailto:sbar...@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 <fpi...@apple.com >>>>>>>>>>>> <mailto:fpi...@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@lists.webkit.org <mailto:webkit-dev@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@lists.webkit.org <mailto:webkit-dev@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@lists.webkit.org <mailto:webkit-dev@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@lists.webkit.org > https://lists.webkit.org/mailman/listinfo/webkit-dev
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org https://lists.webkit.org/mailman/listinfo/webkit-dev
