[lwip-users] RE:[lwip] Suggestion: javadoc

[Paul Sheer]

------=_Part_1107_3575358.1029838529278
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit


This is probably going to make people reel, but...

I invented my own documentation format: a simple
awk script that converts plain ascii into nice
HTML. This allows documentation in the two
most popular formats to be supported: text
and HTML. I have really found that its simplicity
overrides any advantages gained by sgml, roff, etc.
It has the advantage that:

  - awk is supported on every Unix platform, nothing
  need be installed to compile documentation.

  - docs can be read without compiling.

  - web docs will always be in sync with ascii docs.
  because they recompile instantly with each build.

The script is attached.

A sample document is:


LwIP: Light Weight IP Stack
=====================

The double line creates a major header. Here is an
example of an indented list:

  1. This paragraph will be indented.

  2. So will this one.

Or perhaps like:

  - This "bulletted" item will be indented when
  rendered in HTML

URLs will be turned into hyperlinks for example
http://this.com/ will become a hyperlink in HTML.

Images will be creates as image links. For example
(See someimg.jpg.)

You get the idea

-paul



Powered by World Online - http://www.worldonline.co.za


------------- Original Message --------------
From:       address@hidden
To:         address@hidden
Cc:          
Date:       Tue,08/20/2002 09:32:38
Subject:    [lwip] Suggestion: javadoc

Hello,

now that work is underway to have a CVS lwIP tree, I would
suggest to standardize on a (self)documentation format.

Proposal is JavaDoc format.

Arguments have been given earlier (search the mailing list
on "javadoc" and "doxygen") and I recall there was much
agreement on this.

Regards,

Leon Woestenberg

Axon Digital Design
Phone: +31 13 511 6666
Fax: +31 13 511 4151
web: www.axon.tv

================================================================================

=====================
The information contained in this communication is confidential and is
intended
solely for the use of the individual or entity to whom it is addressed.
Axon
Digital Design Group is neither liable for the proper nor for the complete
transmission of the information contained in this communication nor for any

delay in its receipt. Axon Digital Design Group does not guarantee that the

integrity of this communication has been maintained nor that the
communication
is free of viruses, interceptions or interference. If you are not the
intended
recipient of this communication, you are hereby notified that reading,
disseminating, distributing or copying this message is strictly prohibited.
In
that case please return the communication to the sender and delete and
destroy
all copies. In carrying out its engagements, Axon Digital Design Group
applies
general terms and conditions, which contain a clause that limits its
liability.
A copy of these terms and conditions is available on request free of
charge.
================================================================================

=====================

[This message was sent through the lwip discussion list.]

------=_Part_1107_3575358.1029838529278
Content-Type: application/octet-stream; name=txt2html.awk
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename=txt2html.awk

BEGIN {
    oldindent=0
    indent=0
    head=1
    l=""
}
{
    lll=ll
    ll=l
    l=$0
    gsub("<", "\\&lt;", l)
    gsub(">", "\\&gt;", l)
    gsub("http://[^ ]+", "<A href=\"&\">&</A>", l)
    l = gensub("^[(]See ([^.]+[.](jpg|jpeg|png|gif))[.]?[)]$", "<IMG 
src=\"\\1\" align=\"center\" border=\"1\">", "g", l)
    l = gensub("[(]See ([^.]+[.](jpg|jpeg|png|gif))[.]?[)]", "<IMG src=\"\\1\" 
align=\"right\" border=\"1\">", "g", l)
    l = gensub("^[[]See ([^.]+[.](jpg|jpeg|png|gif))[.]?[]]$", "<IMG 
src=\"\\1\" align=\"center\" border=\"0\">", "g", l)
    l = gensub("[[]See ([^.]+[.](jpg|jpeg|png|gif))[.]?[]]", "<IMG src=\"\\1\" 
align=\"right\" border=\"0\">", "g", l)
    if (match (l, "[-][-][-][-][-][-]") == 1) {
        print "<HR><A name=\"head" head "\"><B><FONT size=\"+1\">" ll 
"</FONT></B></A>"
        print "<A href=\"#head" head "\"><B>" ll "</B></A><BR>" > 
"contents.html"
        head=head+1
        l=""
    } else if (match (l, "[=][=][=][=][=][=]") == 1) {
        print "<B><FONT size=\"+2\">" ll "</FONT></B><P>" > "title.html"
        l=""
    } else {
        if (ll == "") {
            if (indent) {
                print "</TD></TR></TABLE>"
                indent = 0
            }
            if (l != "")
                print "<P>"
        } else {
            gsub("      ", "        ", ll)
            i=match(ll, "[ ]+([-]|[1-9][0-9]*[.])[ ]")
            if (i == 1 && lll == "") {
                q = gensub("^[ ]+([-]|[1-9][0-9]*[.])[ ].+$", "\\1", "", ll)
                t = gensub("^([ ]+).+$", "\\1", "", ll)
                if (indent > 0)
                    print "</TD></TR></TABLE>"
                oldindent = indent
                indent = length(t)
#               gsub(" ", "  ", t)
                for(c = 0; c < length(q); c++)
                    gsub("^[ ]", "", t)
                gsub(" ", "\\&nbsp;", t)
                gsub("^[ ]+([-]|[1-9][0-9]*[.])[ ]", "", ll)
                print "<TABLE width=\"100%\" border=0 rules=\"none\" 
frame=\"void\" cols=\"2\" cellspacing=\"0\" cellpadding=\"0\">"
                print "<TR VALIGN=\"top\"><TD width=\"1%\" 
VALIGN=\"top\"><B><CODE>" t q "</CODE></B>&nbsp;&nbsp;</TD><TD>"
            }
            for(c = 0; c < indent; c++)
                gsub("^[ ]", "", ll)
            if (ll == "")
                print "<P>"
            else {
                i = match(ll, "[ ]")
                if (i == 1) {
                    t = gensub("^([ ]*).*$", "\\1", "", ll)
#                   gsub(" ", "  ", t)
                    gsub(" ", "\\&nbsp;", t)
                    gsub("^[ ]*", "", ll)
                    gsub(" ", "\\&nbsp;", ll)
                    print "<CODE>" t "</CODE>" ll "<BR>"
                } else {
                    print ll
                }
            }
        }
    }
}


------=_Part_1107_3575358.1029838529278--

[This message was sent through the lwip discussion list.]