Rich Morin on packaging, documentation, metadata

Posted 17 Jun 2000 at 08:18 UTC by schoen Share This

The hacker and PTF founder Rich Morin posted a link to a draft of an article about packaging, documentation, and metadata. I think it will be of interest to some people here.

The link was sent to the FSB list and some other places. The article talks about modular systems and problems in documenting various aspects of how components are meant to be put together. There is some further commentary on the "cars with hoods welded shut" theme (mechanics also need comprehensive documenation and parts lists, to work efficiently), discussion of "metadata" about software packages (not quite the same thing as filesystem metadata), talks about successful techniques and interesting trends, and finally makes a very ambitious proposal for unifying all sorts of things.

The article is called "Integrating package management and documentation". Have a look if you're interested; it just had an "Advogato feel" about it when I saw it.

Some people will say "oh, no, not another ambitious proposal", but even if you don't have a taste for ambitious proposals, you may find something interesting here. If so, Rich Morin would like comments on his draft.

Ideas along the same line - DB, posted 20 Jun 2000 at 16:23 UTC by craig » (Apprentice)

I don't necessarily know a lot about automake/configure, but it seems to me everyone wants to replace the existing tools. This makes some sense, but in another sense, they seem to be perfectly good tools that everyone is used to.

Why don't we build a database, that can store all this information that configure, or debian's .deb packaging needs, or BSD's configuration needs, and then have output plugins for each different type of data.

so for isntance, there is a uniform way to put this data IN the DB, then once it's inside the Database, we have different output formats, a browseable repository , say on the web or something, and then these plugins for configure scripts, or automake, or what have you.

just a suggestion. Myabe someday I'll have some time to even play with this idea.

Encurage him, it's good., posted 20 Jun 2000 at 16:37 UTC by Ankh » (Master)

Commando was a Good Idea: think about auto-completion of command- line options complete with an understanding that a particular option must be followed by the name of a file that already exists, for example. But generating the software from the man page isn't too good: better to generate the manual page synopsis from the code, and to have commando ask the software about options, as I think some patches to bash can do.

Rich's ideas about packaging are spot on. David Tilbrook's early work was interesting, but required too much of an idiosyncratic environment for widespread adoption.

The API documentation for my lq-text package (it's in PDF) was generated from SGML comments in the C code for the various libraries involved, and I found that this was an effective way of getting me to keep the documentation up to date.

Scripting languages like Perl and Python push the code boundary: they reduce the number of people excluded from understanding the application, because the code is higher level and easier to read.

Shell scripts take this even further.

This led me to think (in 1984 or so) that the best way to write applications would be a very high level language that was easy to understand, that connected together modules that could be written in a more cryptic language (e.g. Perl), which in turn might call C code.

In this way, the top-level code becomes part of its own documentation, and not in a way (like TeX's Web) that requires the reader to understand the code.

All of this is only necessary because the computer is too stupid to be able to explain the problem well enough (in context), together with the user's needs, that it can't explain how the program is to be used. I don't expect that to change in the near future.

In the meantime, anything that helps to relate documentation, code and configuration is To Be Understood And Encouraged.

New Advogato Features

New HTML Parser: The long-awaited libxml2 based HTML parser code is live. It needs further work but already handles most markup better than the original parser.

Keep up with the latest Advogato features by reading the Advogato status blog.

If you're a C programmer with some spare time, take a look at the mod_virgule project page and help us with one of the tasks on the ToDo list!

Share this page