man pages

[schwehr]

Following up on #17, this repo doesn't have man pages. I'm contacting the debian folks (Bas Couwenberg and Francesco Paolo Lovergine) to see about using the ones they package as a starting point.

http://deb.debian.org/debian/pool/main/s/shapelib/shapelib_1.5.0-2.debian.tar.xz

From rules:

ronn -r --date="$(BUILD_DATE)" --manual=shplib debian/man/*.md

It has these markdown sources for man pages:

ls -1 man
dbfadd.md
dbfcat.md
dbfcreate.md
dbfdump.md
dbfinfo.md
Shape_PointInPoly.md
shpadd.md
shpcat.md
shpcentrd.md
shpcreate.md
shpdata.md
shpdump.md
shpdxf.md
shpfix.md
shpinfo.md
shprewind.md
shpsort.md
shptreedump.md
shputils.md
shpwkb.md

[schwehr]

The web subdir has a lot of the necessary content for the command line program (man 1) and C api (man 3).

It would also be nice to write dbf and shape format man pages (man 7)

[schwehr]

Is ronn dead? rtomayko/ronn#111 → https://github.com/apjanke/ronn-ng

ronn-ng is what you get when you sudo apt-get install ronn on debian testing.

However, I have been having a few troubles with ronn. Trying this:

pandoc DBFOpen.md -s -t man | /usr/bin/man -l -

It looks like pandoc might be a better choice.

% BDFOpen(3)

# NAME

DBFOpen - connect an existing xBase format table file

# SYNOPSIS

\#include \<stdio.h\>

DBFHandle *DBFOpen*(const char *pszDBFFile, const char \*pszAccess\);

# DESCRIPTION

The DBFOpen() function should be used to establish access to an existing xBase
format table file.  The returned DBFHandle is passed to other access functions,
and DBFClose() should be invoked to recover resources, and flush changes to disk
when complete.  The DBFCreate() function should called to create new xBase
files.  As a convenience, DBFOpen() can be called with the name of a .shp or
.shx file, and it will figure out the name of the related .dbf file.

# RETURN VALUE

Foo

# EXAMPLES

Bar

# SEE ALSO

Baz

[schwehr]

A first draft of a pandoc driven man page.

% BDFOpen(3)

# NAME

**DBFOpen** - connect an existing xBase format table file

# SYNOPSIS

\#include \<stdio.h\>

DBFHandle **DBFOpend**(const char \**pszDBFFile*, const char \**pszAccess*\);

# DESCRIPTION

The **DBFOpen()** function should be used to establish access to an existing
xBase format table file.  The returned DBFHandle is passed to other access
functions, and **DBFClose()** should be invoked to recover resources, and flush
changes to disk when complete.  The **DBFCreate()** function should called to create
new xBase files.  As a convenience, **DBFOpen()** can be called with the name of a
.shp or .shx file, and it will figure out the name of the related .dbf file.

Parameters:

- *pszDBFFile*:
    The name of the xBase (.dbf) file to access.
- *pszAccess*:
    The fopen() style access string.  At this time only
	"rb" (read-only binary) and "rb+" (read/write binary)
	should be used.

# RETURN VALUE

Returns a *DBFHandle* that is a pointer that must be closed with **DBFClose()**.
Returns a *NULL* pointer on error.

# EXAMPLES

Opening and closing a xBase dbf file:

\`\`\`c
#include <shapefil.h>

DBFHandle handle = DBFOpen(filepath.c_str(), "rb");
if (handle == NULL) {
  exit(EXIT_FAILURE);
}

// Operate on handle.

DBFClose(handle);
\`\`\`

# SEE ALSO

dbfdump(1) dbfinfo(1) DBFClose(3) DBFCreate(3) dbf(7)

Built with pandoc DBFOpen.md -s -t man | /usr/bin/man -l - gives

BDFOpen(3)                                                                                    BDFOpen(3)

NAME
       DBFOpen - connect an existing xBase format table file

SYNOPSIS
       #include <stdio.h>

       DBFHandle DBFOpend(const char *pszDBFFile, const char *pszAccess);

DESCRIPTION
       The DBFOpen() function should be used to establish access to an existing xBase format table file.
       The returned DBFHandle is passed to other access functions, and DBFClose() should be  invoked  to
       recover  resources,  and  flush  changes  to disk when complete.  The DBFCreate() function should
       called to create new xBase files.  As a convenience, DBFOpen() can be called with the name  of  a
       .shp or .shx file, and it will figure out the name of the related .dbf file.

       Parameters:

       • pszDBFFile: The name of the xBase (.dbf) file to access.

       • pszAccess:  The  fopen()  style  access  string.  At this time only “rb” (read-only binary) and
         “rb+” (read/write binary) should be used.

RETURN VALUE
       Returns a DBFHandle that is a pointer that must be closed with DBFClose().  Returns a NULL point‐
       er on error.

EXAMPLES
       Opening and closing a xBase dbf file:

              #include <shapefil.h>

              DBFHandle handle = DBFOpen(filepath.c_str(), "rb");
              if (handle == NULL) {
                exit(EXIT_FAILURE);
              }

              // Operate on handle.

              DBFClose(handle);

SEE ALSO
       dbfdump(1) dbfinfo(1) DBFClose(3) DBFCreate(3) dbf(7)

                                                                                              BDFOpen(3)