Subject: proposal for new format of pkgsrc README.html
To: None <firstname.lastname@example.org>
From: James K. Lowden <email@example.com>
Date: 05/11/2005 03:09:27
I propose a new page format for a binary package's README file, example
above. If we can agree on the format, I'll work up a patch to generate
our new improved pages. (But I haven't yet discovered where that code
Changes that I think are helpful:
* Fewer words, less redundancy.
For example, the headline announces the packages location
(archivers/gtar), and then the text says "The package is located in the
The new format relies on the headline, while converting part of it to an
By reducing the word count and making better use of typographical clues,
the page can be more readily comprehended.
* Much denser presentation of available precompiled binaries.
An experienced user, in particular, will have an easier time scanning the
new Precompiled Binaries table.
* Include DESCR in the body as a quotation.
I don't know why we don't already do this. It takes almost as many words
to say where DESCR is as there are words in most DESCR files.
$ wc -w */*/DESCR |sort -rn |head
I won't comment on the employment of the comma in "GNU tar, is a
full-featured tar command". It, speaks for itself.
* Small jump table at the top of the page, to ease navigation.
* Less important boilerplate advice moved near the end of the page.
I'm not convinced that the Security Vulnerabilities deserves to be so near
the top of every page. I think instead that a vulnerabilty count near the
top is sufficient. If you think it needs more prominence, we could add a
"Known Security Vulnerability" section for those packages whose count is
non-zero. I would insert such a section immediately above Required