[Swan-dev] man pages for our library routines

[D. Hugh Redelmeier]

| From: Paul Wouters <paul at nohats.ca>

| No, it was never a real library. It was basically freeswan developer 
| information in the form of man pages.

It was a library.  Interestingly, it did not depend on the rest of
FreeS/WAN.

It wasn't adopted by other projects, but that's too bad.  It created
some useful abstractions.  It was carefully designed and then evolved in 
light of experience.

One disaster seems to have been part of the Openswan project.  Lots of
other code was moved (badly) into the same tree as the original
library.  It didn't mix because it had various dependencies to code
outside the library.  So the original clean library interfaces were
muddied.  (I may have some of this wrong since I never have understood 
this new modularization.)

| It was good but they were also 
| already littered with “this function is obsolete and will go away” which 
| was a lie.

Lies can and should be fixed.  Usually by changing the code, not the
documentation.  It would have been easy since all obsoleted functions
were replaced by more convenient ones (see "evolved", above).

(We're carrying around too much code that receives no maintenance.  If
we don't maintain it we should probably delete it.  I would guess that
only unmaintained code uses those obsolete functions.)

(Actually, worse than unmaintained code is untested code.  We dare not
maintain untested code for fear of breaking it without ever knowing.)

The claim that a function is obsolete isn't a lie.  That the obsolete
functions are still being used is not a failure of the library.  It is
a failure of the maintainers of the code that uses of those routines.

| I stopped installing them because there were no real consumers for these 
| and they were full of warnings from automatic lint tools etc and they 
| were crappily converted from nroff to xml by me.

I used them.  I was the main customer in FreeS/WAN.

I don't use them now because they aren't easy to use.  I miss them.

(I don't know (remember?) what "lint" you are referring to.  Perhaps I 
could have fixed it -- I used to know troff.)

| > On Aug 22, 2019, at 15:33, Andrew Cagney <andrew.cagney at gmail.com>
| wrote:

| > They're neither read nor maintained because they are external to the
| > source code (and honestly reading the source is more reliable).

No, they were used and maintained.  I used the man pages and not the
code to understand what the functions did.

Henry's coding was pretty reliable.  It did match the man page.

Example: your query was easily answered by reading the man page.

The code of those library routines has hardly been touched since Henry
wrote them.  That's because they were solid, simple, useful, and
stand-alone.