[P4-design] Converting P4_16 spec to html

Chris Dodd chris at barefootnetworks.com
Wed Oct 19 13:10:39 EDT 2016


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-sch
>> olarly-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
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.p4.org/pipermail/p4-design_lists.p4.org/attachments/20161019/d56b70a3/attachment-0002.html>


More information about the P4-design mailing list