doc: Migrate MIGRATION document to Markdown

- Move to Markdown, still readable as plain text I hope
- Simplify and clarify some minor things

Signed-off-by: Joachim Nilsson <troglobit@gmail.com>

6 files changed, 179 insertions, 174 deletions

diff --git a/README.md b/README.md
index c23f33d..346d9fb 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@ Online documentation is available at https://codedocs.xyz/libnet/libnet/
 
 > **NOTE:** Legacy code written for *libnet-1.0.x* is unfortunately
 >           **incompatible** with *libnet-1.1.x* and later.  
->           See the [MIGRATION](doc/MIGRATION) guide for porting help.
+>           See the [Migration Guide](doc/MIGRATION.md) for porting help.
 
 
 Building
diff --git a/debian/libnet1-doc.docs b/debian/libnet1-doc.docs
index 840f83e..933f564 100644
--- a/debian/libnet1-doc.docs
+++ b/debian/libnet1-doc.docs
@@ -2,7 +2,7 @@ README
 doc/CONTRIB
 doc/TODO
 doc/DESIGN_NOTES
-doc/MIGRATION
+doc/MIGRATION.md
 doc/PACKET_BUILDING
 doc/PORTED
 doc/RAWSOCKET_NON_SEQUITUR
diff --git a/doc/MIGRATION b/doc/MIGRATION
deleted file mode 100644
index bfcc722..0000000
--- a/doc/MIGRATION
+++ /dev/null
@@ -1,170 +0,0 @@
-===============================================================================
-    $Id: MIGRATION,v 1.2 2004/01/03 20:31:00 mike Exp $
-    LIBNET 1.1 (c) 1998 - 2004 Mike D. Schiffman <mike@infonexus.com>
-                               http://www.packetfactory.net/libnet
-===============================================================================
-
-
-    MIGRATING YOUR CODE TO LIBNET 1.1 AND QUICKSTART
-
-    Using Libnet 1.1 you will find it MUCH simpler to build and write packets
-    than before.  Instead of the previous five steps (initialize memory,
-    initialize network, build packet, do checksums, write packet) there are
-    now only three steps (initialize library, build packet, write packet).  
-    In order to port your existing code, you will mainly be REMOVING 
-    function calls and variables.
-
-    1) Start with code removal:
-
-        - Remove all calls to libnet_init_packet() / packet malloc()ing and
-          all associated variables.
-        - Remove all calls to libnet_open_raw_sock() / libnet_open_link_layer()
-          and all associated variables.
-        - Remove all calls to libnet_do_checksum() and all associated
-          variables.
-
-    2) Continue with code addition and modification:
-
-        - You will need a single "libnet_t *l" which is your libnet file
-          context and an error buffer:
-
-            libnet_t *l
-            char errbuf[LIBNET_ERRBUF_SIZE];
-
-            l = libnet_init(
-                    LIBNET_RAW4,    /* or LIBNET_LINK or LIBNET_RAW6 */
-                    NULL,           /* or device if you using LIBNET_LINK */
-                    errbuf);
-
-        - The libnet_build functions are largely unchanged with a few
-          important differences:
-
-                1) Packets headers MUST be stacked IN ORDER.  This is
-                   intuitive and shouldn't be a problem.  Due to the way
-                   individual packet header memory is allocated and how 
-                   packet pieces are combined to build a packet they HAVE to 
-                   be built IN ORDER, from the high end of the protocol stack 
-                   on down.  ie: using the raw interface to build a NTP
-                   packet, you would:
-                        libnet_build_ntp(...)
-                        libnet_build_udp(...)
-                        libnet_build_ipv4(...)
-                   To build the same packet using the LINK interface on 
-                   top of ethernet you would:
-                        libnet_build_ntp(...)
-                        libnet_build_udp(...)
-                        libnet_build_ipv4(...)
-                        libnet_build_ethernet(...)
-                1a) There is the option now of using libnet_autobuild_ipv4()
-                    and libnet_autobuild_ethernet() which have fewer 
-                    arguments and smaller stack frames and are a bit more
-                    convenient.
-                2) The libnet_build functions return a libnet_ptag_t datatype
-                   on success or -1 on error.  This ptag is your
-                   "protocol/packet tag" so you can find this header again
-                   if you needed to modify it later on.  If you don't need
-                   to modify the packet header you can throw this value
-                   away.  You should definitely check for error now on
-                   your build functions.  Alot's going on down there fellas.
-                2a) NOTE that after packets are built, they may accessed
-                    independently of construction order via the saved ptag.
-                3) They NO LONGER ACCEPT BUFFER ARGUMENTS.  This is ALL
-                   done internally.  The last TWO arguments are the libnet
-                   context you created in your call to libnet_init() and
-                   an OPTIONAL ptag argument.  The ptag argument, if non-zero,
-                   specifes a packet tag to an ALREADY EXISTING packet header
-                   that will be OVERWRITTEN with the values specified in
-                   this libnet_build function call.  This is how you modify
-                   existing packet header pieces.  If this ptag is 0,
-                   a new protocol block is allocated and the packet is
-                   pushed down on the "protocol stack".
-                4) For the functions that build headers that have checksums
-                   these are NOW SPECIFIED AS AN ARGUMENT.  This adds more
-                   flexibility in how checksums are done (you can leave the
-                   field 0, put in a random value, precompute it on your own,
-                   or let the library do it).  By default, when you build
-                   a header, a "DO_CHECKSUM" flag will be set.  This means
-                   the library will compute the checksum for the header
-                   and possibly over the data before the packet is written.
-                   To clear this flag, there is a special macro you
-                   can call on the ptag refering to that header.
-                5) For the functions that have a length, it now specifies
-                   the TOTAL packet length from that protocol unit on down.
-                   For IP, that would be the entire packet length.  For
-                   TCP, that would be TCP and any possible data.
-                6) Nomenclature support for the eventual support of ipv6
-                   has been added.
-
-            libnet_ptag_t ip_tag;
-            libnet_ptag_t tcp_tag;
-
-            tcp_tag = libnet_build_tcp(
-                src_prt,            /* source TCP port */
-                dst_prt,            /* destination TCP port */
-                0xffff,             /* sequence number */
-                0x53,               /* acknowledgement number */
-                TH_SYN,             /* control flags */
-                1024,               /* window size */
-                0xd00d,             /* checksum */
-                0,                  /* urgent pointer */
-                LIBNET_TCP_H        /* TCP packet size */
-                NULL,               /* payload (none) */
-                0,                  /* payload length */
-                l,                  /* libnet context */
-                0);                 /* ptag */
-
-            ip_tag = libnet_build_ipv4(
-                LIBNET_TCP_H + LIBNET_IPV4_H,/* total packet len */
-                IPTOS_LOWDELAY,     /* tos */
-                ip_id,              /* IP ID */
-                0,                  /* IP Frag */
-                64,                 /* TTL */
-                IPPROTO_TCP,        /* protocol */
-                0,                  /* checksum */
-                src_ip,             /* source ip */
-                dst_ip,             /* dest ip */
-                NULL,               /* payload (none) */
-                0,                  /* payload size */
-                l,                  /* libnet context */
-                0);                 /* ptag */
-
-            Now, if you wanted to modify one of these headers in a loop
-            somewhere you would:
-
-            int i;
-            for (ip_tag, tcp_tag = LIBNET_PTAG_INITIALIZER, i = 0; i < 10; i++)
-            {
-                tcp_tag = libnet_build_tcp(++src_prt, ..., l, tcp_tag);
-                ip_tag = libnet_build_ipv4(..., ++ip_id, ..., l, ip_tag);
-                /* do something */
-            }
-            Since we are specifying a ptag for an existing header, the
-            build function will NOT create a new header and append it to
-            the list, it will FIND the one referenced by the ptag and UPDATE
-            it.  Since there is nothing new being created, order is NOT
-            important here.
-
-            Also note that it's perfectly fine to wrap the loop around the
-            initial building of the packets.  Since we're initializing the
-            ptags (to be zero), the first call into the builder functions
-            will allocate the memory and create the packet blocks.  These
-            calls will return ptag values.  The next calls will modify
-            these headers since the ptags will not be NULL.
-
-    - Finally, we write the packet.  Checksums are computed, by default
-      for each protocol header that requires one.  If the user specifies
-      a non-zero value, by default, this will be used INSTEAD of a
-      libnet computed checksum.  This behavior is overridable with:
-      
-    Turn ON checksums for header referenced by ptag:
-        libnet_toggle_checksum(l, ptag, 1)
-
-    Turn OFF checksums for header referenced by ptag:
-        libnet_toggle_checksum(l, ptag, 0)
-
-    Note, the packet header MUST exist before you can toggle this setting.
-
-        int c;
-        c = libnet_write(l);
-
-    Boom.  You're done.  Now go read the sample code.
diff --git a/doc/MIGRATION.md b/doc/MIGRATION.md
new file mode 100644
index 0000000..9a1863f
--- /dev/null
+++ b/doc/MIGRATION.md
@@ -0,0 +1,175 @@
+Migrating Your Code to libnet 1.1 or Later
+==========================================
+by Mike D. Schiffman <mike@infonexus.com>
+
+Using Libnet 1.1 you will find it MUCH simpler to build and write packets than
+before.  Instead of the previous five steps (initialize memory, initialize
+network, build packet, do checksums, write packet) there are now only three
+steps (initialize library, build packet, write packet).
+
+In order to port your existing code, you will mainly be *removing* function
+calls and variables.
+
+
+Cleanup
+-------
+
+Start with code removal:
+
+- Remove all calls to `libnet_init_packet()` packet `malloc()`ing, and all
+  associated variables
+- Remove all calls to `libnet_open_raw_sock()`, `libnet_open_link_layer()`,
+  and all associated variables
+- Remove all calls to `libnet_do_checksum()` and all associated variables
+
+
+Code Changes
+------------
+
+Continue with code addition and modification.
+
+You will need a single `libnet_t *l` which is your libnet file context and an
+error buffer:
+
+    libnet_t *l
+    char errbuf[LIBNET_ERRBUF_SIZE];
+
+    l = libnet_init(
+            LIBNET_RAW4,    /* or LIBNET_LINK or LIBNET_RAW6 */
+            NULL,           /* or device if you using LIBNET_LINK */
+            errbuf);
+
+The `libnet_build_*()` functions are largely unchanged with a few important
+differences:
+
+1. Packets headers *MUST* be stacked *IN ORDER*.  This is intuitive and
+   shouldn't be a problem.  Due to the way individual packet header memory is
+   allocated and how packet pieces are combined to build a packet they *HAVE*
+   to be built *IN ORDER*, from the high end of the protocol stack on down.
+   i.e.: using the raw interface to build a NTP packet, you would:
+
+        libnet_build_ntp(...)
+        libnet_build_udp(...)
+        libnet_build_ipv4(...)
+
+   To build the same packet using the LINK interface on top of ethernet you
+   would:
+
+        libnet_build_ntp(...)
+        libnet_build_udp(...)
+        libnet_build_ipv4(...)
+        libnet_build_ethernet(...)
+
+   > **Note:** There is the option now of using `libnet_autobuild_ipv4()` and
+   > `libnet_autobuild_ethernet()` which have fewer arguments and smaller
+   > stack frames, and are a bit more convenient.
+
+2. The `libnet_build_*()` functions return a `libnet_ptag_t` datatype on
+   success or -1 on error.  This ptag is your "protocol/packet tag" so you can
+   find this header again if you needed to modify it later on.  If you don't
+   need to modify the packet header you can throw this value away.  You should
+   definitely check for error now on your build functions.  A lot's going on
+   down there fellas.
+
+   > **Note:** that after packets are built, they may be accessed
+   > independently of construction order via the saved ptag.
+
+3. They *NO LONGER ACCEPT BUFFER ARGUMENTS*.  This is *ALL* done internally.
+   The last *TWO* arguments are the libnet context you created in your call to
+   `libnet_init()` and an *OPTIONAL* ptag argument.  The ptag argument, if
+   non-zero, specifes a packet tag to an *ALREADY EXISTING* packet header that
+   will be *OVERWRITTEN* with the values specified in this `libnet_build_*()`
+   function call.  This is how you modify existing packet header pieces.  If
+   this ptag is 0, a new protocol block is allocated and the packet is pushed
+   down on the "protocol stack".
+4. For the functions that build headers that have checksums these are *NOW
+   SPECIFIED AS AN ARGUMENT*.  This adds more flexibility in how checksums are
+   done (you can leave the field 0, put in a random value, precompute it on
+   your own, or let the library do it).  By default, when you build a header,
+   a `DO_CHECKSUM` flag will be set.  This means the library will compute the
+   checksum for the header and possibly over the data before the packet is
+   written.  To clear this flag, there is a special macro you can call on the
+   ptag refering to that header.
+5. For the functions that have a length, it now specifies the *TOTAL* packet
+   length from that protocol unit on down.  For IP, that would be the entire
+   packet length.  For TCP, that would be TCP and any possible data.
+6. Nomenclature support for the eventual support of ipv6 has been added.
+
+### Example
+
+    libnet_ptag_t ip_tag;
+    libnet_ptag_t tcp_tag;
+
+    tcp_tag = libnet_build_tcp(
+        src_prt,            /* source TCP port */
+        dst_prt,            /* destination TCP port */
+        0xffff,             /* sequence number */
+        0x53,               /* acknowledgement number */
+        TH_SYN,             /* control flags */
+        1024,               /* window size */
+        0xd00d,             /* checksum */
+        0,                  /* urgent pointer */
+        LIBNET_TCP_H        /* TCP packet size */
+        NULL,               /* payload (none) */
+        0,                  /* payload length */
+        l,                  /* libnet context */
+        0);                 /* ptag */
+
+    ip_tag = libnet_build_ipv4(
+        LIBNET_TCP_H + LIBNET_IPV4_H,/* total packet len */
+        IPTOS_LOWDELAY,     /* tos */
+        ip_id,              /* IP ID */
+        0,                  /* IP Frag */
+        64,                 /* TTL */
+        IPPROTO_TCP,        /* protocol */
+        0,                  /* checksum */
+        src_ip,             /* source ip */
+        dst_ip,             /* dest ip */
+        NULL,               /* payload (none) */
+        0,                  /* payload size */
+        l,                  /* libnet context */
+        0);                 /* ptag */
+
+Now, if you wanted to modify one of these headers in a loop somewhere you
+would:
+
+    int i;
+    for (ip_tag, tcp_tag = LIBNET_PTAG_INITIALIZER, i = 0; i < 10; i++)
+    {
+        tcp_tag = libnet_build_tcp(++src_prt, ..., l, tcp_tag);
+        ip_tag = libnet_build_ipv4(..., ++ip_id, ..., l, ip_tag);
+        /* do something */
+    }
+
+Since we are specifying a ptag for an existing header, the build function will
+NOT create a new header and append it to the list, it will FIND the one
+referenced by the ptag and *UPDATE* it.  Since there is nothing new being
+created, order is NOT important here.
+
+Also note that it's perfectly fine to wrap the loop around the initial
+building of the packets.  Since we're initializing the ptags (to be zero), the
+first call into the builder functions will allocate the memory and create the
+packet blocks.  These calls will return ptag values.  The next calls will
+modify these headers since the ptags will not be NULL.
+
+### Writing the Packet
+
+Finally, we write the packet.  Checksums are computed, by default for each
+protocol header that requires one.  If the user specifies a non-zero value, by
+default, this will be used *INSTEAD* of a libnet computed checksum.  This
+behavior is possible to override with:
+  
+Turn ON checksums for header referenced by ptag:
+
+    libnet_toggle_checksum(l, ptag, 1)
+
+Turn OFF checksums for header referenced by ptag:
+
+    libnet_toggle_checksum(l, ptag, 0)
+
+Note, the packet header MUST exist before you can toggle this setting.
+
+    int c;
+    c = libnet_write(l);
+
+Boom.  You're done.  Now go read the sample code.
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 41e0224..8ed2ef1 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,5 +1,5 @@
 SUBDIRS        = man
-dist_doc_DATA  = MIGRATION RAWSOCKET_NON_SEQUITUR
+dist_doc_DATA  = MIGRATION.md RAWSOCKET_NON_SEQUITUR
 EXTRA_DIST     = fixmanpages.in libnet.Pod
 EXTRA_DIST    += api-main.md api-head.html api-foot.html api-style.css
 DISTCLEANFILES = libnet.tag
diff --git a/doc/libnet.Pod b/doc/libnet.Pod
index 67643b9..cb80bbb 100644
--- a/doc/libnet.Pod
+++ b/doc/libnet.Pod
@@ -43,7 +43,7 @@ F<libnet/libnet-functions.h>, F<libnet/libnet-macros.h> or any of the others.
 =head1 BACKWARDS COMPATIBILITY
 
 Your old code (circa libnet B<1.0.x>) WILL NOT WORK with libnet> B<E<gt>=1.1.x>.
-See B<doc/MIGRATION> for easy steps on porting your old code.
+See B<doc/MIGRATION.md> for easy steps on porting your old code.
 
 =head1 SEE ALSO