[P4-design] Converting P4_16 spec to html

Calin Cascaval cascaval at barefootnetworks.com
Wed Oct 19 12:48:56 EDT 2016


+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/ <https://www.madoko.net/>
> 
> -N
> 
> On Wed, Oct 19, 2016 at 9:08 AM, Nate Foster <jnfoster at cs.cornell.edu <mailto: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/ <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 <mailto: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 <mailto: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 <mailto:P4-design at lists.p4.org>
> http://lists.p4.org/mailman/listinfo/p4-design_lists.p4.org <http://lists.p4.org/mailman/listinfo/p4-design_lists.p4.org>
> 
> 
> 
> 
> _______________________________________________
> P4-design mailing list
> P4-design at lists.p4.org <mailto:P4-design at lists.p4.org>
> http://lists.p4.org/mailman/listinfo/p4-design_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/401c73aa/attachment-0002.html>


More information about the P4-design mailing list