http://www.schemamania.org/oak/pkgsrc/archivers/gtar/README.html

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
is.)

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
"archivers/gtar" directory.".  

The new format relies on the headline, while converting part of it to an
anchor. 
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
  320158 total
     282 games/kdegames3/DESCR
     271 games/xdemineur/DESCR
     256 sysutils/gkrellm-share/DESCR
     255 graphics/openexr/DESCR
     254 benchmarks/bonnie/DESCR
     252 sysutils/gkrellm-server/DESCR
     250 net/adns/DESCR
     247 sysutils/vip/DESCR
     246 x11/XmHTML/DESCR

I won't comment on the employment of the comma in "GNU tar, is a
full-featured tar command".  It, speaks for itself.  

Other features: 

*  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
Packages.  

Waddya say?  

--jkl