I improved the readability of this manpage, both as a formatted document and for source review. I added a few macros, including one which presents the examples as constant-width (when viewed by something which is capable of both Roman and CW, otherwise it's all CW :) I expanded the terminology section, pulling in definitions from various other sources. It looked like that was on somebody's to-do list, anyway.
Created attachment 24616 [details] groff source for new portage(5) manpage
some of it i like some of i dont ;) i'll spend sometime going through it and merging it with the current one
while you're at it, do you think you can change the descriptions for the /etc/make.profile section to explain the new stacked profile stuff ? (ask me if you need info)
ok, here's what i liked and what i didnt (i.e. what i added to cvs and what i didnt ;]) left out: - the ninja foo at the beginning of the document ... i dont think the added complexity is worth the resulting changes in readability ... - the changes to the way 'Format' was displayed ... i used a bulleted list on purpose because if the text wraps around, it's easy to see each point ... and i think a bulleted list in these cases is more readable than a block of text - the bolding/changing of spacing of everything in the SYNOPSIS section - some of the descriptions in the GLOSSARY section ... i think adding all of those isnt really needed - the removal of spacing lines between directory/file sections ... i think it hurts readability - some of the changes from `` to "" ... i use the `` to clearly indicate a command while "" is more of output or something you type into a file - the changes from using \fB\fR or \fI\fR to .BR and .IR in the middle of paragraphs ... i think it hurts the source-readability - the comments ... i think they may help out, but they're not really needed ... and instead of using a string of .:':. to help break up the source, i use syntax highlighting (if you use nano, it has basic support for groff/manpages/whatever this stuff is) added to cvs: - i went through and added most of the changes in language (if you think i missed something please point it out) - i liked the way you tried to make the format/example sections stick out so instead of using spacing, i added .I before each 'Format:' and 'Example:' - changed the '' and "" usage to all be "" - a few of the parts of the GLOSSARY - added \fB\fR formatting to files/paths that are described elsewhere in the manpage - changed the \fB\fR to .BR (and similar) when used in a header what i would like to add but not sure how: - i want to use the half spacing you have but only at the top dir level ... it would be quite useful in gaining more spacing in the format/example sections: /etc make.globals The global default settings ... i like how there is half space in front of /etc but normal for the rest ...
Created attachment 26384 [details, diff] patch to portage.5,v 1.4 You make the half-indents using the '.SS' macro. And please pardon the delay.
anyway, I am glad that something I did was actually considered useful
