lkml.org 
[lkml]   [2007]   [Aug]   [10]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: Documentation files in html format?
    Hi Stephen,

    On Thu, Aug 09, 2007 at 11:31:22AM +0100, Stephen Hemminger wrote:
    > Since the network device documentation needs a rewrite, I was thinking
    > of using basic html format instead of just plain text. But since this would
    > be starting an new precedent for kernel documentation, some it seemed
    > like a worthwhile topic for discussion.

    I've read pro-plain text arguments, so I'll not repeat them. I also see
    another advantage to plain text : it's very easy to draw ascii-art
    diagrams of anything. It only takes a few minutes, is always inline
    and readable with any tool. Look at the bonding doc I wrote and updated
    in 2000, people have updated or duplicated some of the diagrams when
    they have added features. Something they would definitely not have done
    if it had required some strange tool.

    Also, the advantage of plain text is that it stays compatible with
    everything though the years. Had I used some random tool in 2000 for
    this, I'm not sure the tool would still exist right now. Look at RFCs.
    Nothing fancy, just readable. Even the TCP FSM in rfc793 from 26 years
    ago is readable, understandable, and updatable by anybody (though it's
    a little mit messy). And it's somewhat an extreme case ;-)

    I'd prefer that you define some writing conventions for plain-text
    documents that anyone should try follow, starting with the 80-cols
    limit to make Davem happy. I think that many of us can help define
    such a "standard" indicating how to underline subtitles, how to
    enumerate a list, how to avoid using tabs, how to write boxes and
    arrows in their diagrams, etc...

    Best regards,
    Willy

    -
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

    \
     
     \ /
      Last update: 2007-08-10 22:27    [W:3.879 / U:0.228 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site