[P4-design] Converting P4_16 spec to html

Dan Talayco dan.talayco at gmail.com
Thu Oct 20 10:50:56 EDT 2016


Madoko looks promising.

Rapidly reviewing changes (as well as generating changes across varying
sources) is really important for this process.

One banal note regarding diffs and TeX: It is easier to review diffs in TeX
source, but that is only true when the source text uses certain
conventions. For example, keeping line lengths short. Many people are using
editors which do not wrap lines explicitly and as a result, changing one
word results in the entire paragraph being marked.

I poked around briefly, but don't see any information about how Madoko
handles this part of the flow. It's worth examining.

-Dan


On Wed, Oct 19, 2016 at 10:10 AM, Chris Dodd <chris at barefootnetworks.com>
wrote:

> The peculiar requirement for our situation is that we need a good way of
> supporting both code snippets and grammar snippets as two distinct things
> (In the original P4 spec, these showed up as blue boxes and green boxes --
> in the current spec these are just different font and blueish boxes; I
> think the original was slightly nicer).  The original pylatex stuff also
> had support for automatically pulling all the grammar pieces together for
> the appendix; nice, but manually creating the appendix isn't too tough.
>
> On Wed, Oct 19, 2016 at 9:48 AM, Calin Cascaval <
> cascaval at barefootnetworks.com> wrote:
>
>> +1 for a textual representation.
>>
>> I had used doxygen in the past -- you can write dox files and generate
>> both latex and html. Setting it up is a bit of pain, but once you have it,
>> it is easy to extend with examples directly from source code.
>>
>> However, markdown is more github-ish, so my vote is to try Madoko. I can
>> do the porting if we agree.
>>
>> --
>> Thanks, Calin
>>
>> On Oct 19, 2016, at 9:13 AM, Nate Foster <jnfoster at cs.cornell.edu> wrote:
>>
>> Sorry, this is the right link for Makado: https://www.madoko.net/
>>
>> -N
>>
>> On Wed, Oct 19, 2016 at 9:08 AM, Nate Foster <jnfoster at cs.cornell.edu>
>> wrote:
>>
>>> I agree that having a textual markup format would work better for
>>> frenetic editing by a larger group.
>>>
>>> I would support porting the spec and am happy to help with the execution
>>> if we decide to do it.
>>>
>>> LaTeX or Markdown could work well. Daan Leijn's Makado framework is also
>>> pretty slick (https://www.microsoft.com/en-
>>> us/research/video/madoko-a-scholarly-markdown/)
>>>
>>> -N
>>>
>>> On Wed, Oct 19, 2016 at 8:57 AM, Chris Dodd <chris at barefootnetworks.com>
>>> wrote:
>>>
>>>> I think that would be even worse than word for seeing diffs and merging
>>>> stuff, as html is unreadable without tools and tools tend to randomly munge
>>>> it.
>>>>
>>>> If we want something that is diff-able and merge-able, latex is
>>>> basically the only choice.
>>>>
>>>> On Wed, Oct 19, 2016 at 8:48 AM, Mihai Budiu <mbudiu at vmware.com> wrote:
>>>>
>>>>> Hello.
>>>>>
>>>>>
>>>>>
>>>>> Would it be a good idea to convert the spec to html + css? This would
>>>>> make it easier to see diffs and accept contributions on github – especially
>>>>> these days there are a lot of small edits. The html would probably have to
>>>>> be hand-written and edited, since most tools generate very complicated
>>>>> structures. I imagine there would be some significant one-time effort
>>>>> converting from word.
>>>>>
>>>>>
>>>>>
>>>>> Also, an html spec is easier to share on the web. However, html is
>>>>> probably not as pleasant to convert to pdf.
>>>>>
>>>>>
>>>>>
>>>>> Mihai
>>>>>
>>>>> _______________________________________________
>>>>> P4-design mailing list
>>>>> P4-design at lists.p4.org
>>>>> http://lists.p4.org/mailman/listinfo/p4-design_lists.p4.org
>>>>>
>>>>>
>>>>>
>>>>
>>>> _______________________________________________
>>>> P4-design mailing list
>>>> P4-design at lists.p4.org
>>>> http://lists.p4.org/mailman/listinfo/p4-design_lists.p4.org
>>>>
>>>>
>>>>
>>>
>> _______________________________________________
>> P4-design mailing list
>> P4-design at lists.p4.org
>> http://lists.p4.org/mailman/listinfo/p4-design_lists.p4.org
>>
>>
>>
>
> _______________________________________________
> P4-design mailing list
> P4-design at lists.p4.org
> http://lists.p4.org/mailman/listinfo/p4-design_lists.p4.org
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.p4.org/pipermail/p4-design_lists.p4.org/attachments/20161020/e2f3ec06/attachment-0002.html>


More information about the P4-design mailing list