Please review for Man-DB changes

DJ Lucas dj at linuxfromscratch.org
Fri Oct 24 22:40:59 PDT 2008


Alexander E. Patrakov wrote:
> DJ Lucas wrote:
>
>   
>> 6.47.2. Non-English Manual Pages in LFS
>>     

>> LFS also used the legacy
>> encodings in previuos versions of the book. This was chosen because
>>     
>
> And also, the text is misleading: it supports the assumption that 
> now legacy encoding are not used.
>   
"LFS also used *only* legacy encodings..." could've fixed that, but the 
short version you gave below is more to the point, though we loose some 
of the historical value of the decision to use Man-DB over Man.
>   
>> of the ease of configuration associated with Man-DB. Additionally,
>>     
>
> Readers won't understand this.
>
>   
>> Man-DB provided support for Chinese and Japanese locales, and limited
>> support for Korean, whereas Man did not at that time.
>>     
>
> Man does support Japanese, by means of the JNROFF directive.
>
>   
This still requires another package, and more configuration.
>> In contrast, the setup in Fedora Core expects all manual pages to be
>> UTF-8 encoded, and stored in directories without suffixes.
>>     
>
> Duplicate information. So we need to agree on the examples of directory 
> layout that we demonstrate, and their order.
>
> And IMHO, the whole text above (right from the heading) needs to be 
> reordered. Something like this:
>
> ===================
> Some packages provide non-English manual pages. They are displayed 
> correctly only if their location and encoding matches the expectation of 
> the "man" program. However, different Linux distributions have different 
> policies (expressed in the choice of the "man" program, its 
> configuration and patches applied to it) concerning the character 
> encoding in which manual pages are stored in the filesystem.
>
> E.g., Debian previously required Russian manual pages to be encoded in 
> KOI8-R and to be placed in /usr/share/man/ru. Now, in addition, their 
> "man" program searches for UTF-8 encoded Russian manual pages in 
> /usr/share/man/ru.UTF-8. On the other hand, Fedora stores UTF-8 encoded 
> Russian manual pages in /usr/share/man/ru and their "man" program 
> doesn't look into /usr/share/man/ru.UTF-8.
> ===================
>
> Yes, a significant portion of the text has been thrown away.
>
>   
>> Disagreement about the expected encoding of manual pages amongst
>> distribution vendors, has led to confusion for upsteam package
>> maintainers. Some packages contain, UTF-8 manual pages, while others
>>     
>
> No comma after "contain".
>
>   
>> ship with manual pages in legacy encodings.
>>     
>
> At this point, we (as I think) have clearly stated the problem for 
> upstream maintainers.
>
>   
Right here is where we can insert the "mess" that others are leaving the 
up to the user to fix.   I wonder how many others we would be referring 
to, however.  Debian and RedHat provide the base for many popular 
distributions.
> After that, we can explain our setup: "Man-DB uses the extension of the 
> directory name...", including the examples, even though they duplicate 
> our explanation of the modern Debian setup (not all readers know that 
> Debian uses Man-DB).
>
> None of the two quotes below should appear in the book.
>
>   
>> Unlike the Man/Groff
>> setup in Fedora Core, Man-DB can make very good decisions about the
>>     
>
> Only if the user placed the manual pages correctly.
>
>   
>> on disk encoding and present the information to the user in their
>> prefered format, without complex configurations.
>>     
>
> Man in Fedora Core ships preconfigured, and, due to exclusive use of 
> UTF-8, there are no decisions to make. The setup is completely 
> transparent to the end users as long as only prepackaged software is used.
>   
I hadn't considered that.  What I was shooting for was again, to express 
how much work would be involved for LFS to use the RedHat approach, 
further justifying the choice of Man-DB.
> Please stop trying to show that the Debian setup is better. The only 
> benefits are that it allows for a transition period when UTF-8 and 
> legacy manual pages coexist in different directories, and that it 
> requires less patches than the approach from RedHat. 
We disagree here.  I do want to continually drive home the idea that it 
is *better suited* for our purpose, however it keeps coming off as 
Man-DB is better.  We have to support the configuration for everyone, 
and can do so by explaining the correct directory layout vs. explaining 
man.conf, groff, adding a hint about jgroff, adding multiple heavy 
handed patches, etc.

> I take back my 
> statement about lengthy configuration, it is invalid with RedHat Groff 
> (but valid with the upstream Groff).
>   
Only because the distribution ships it pre-configured.  For us to go 
that route, would still be difficult, and error prone for all of the LFS 
family.
> Yes, I cheated by 
> removing the note about the mess present in most distributions, but I 
> don't see where to reinsert it.
>
>   
It should still be mentioned...but maybe not so directly.  I don't want 
to come off as looking down on other distros, but rather acknowledging 
the problem and maybe even lending a helping hand (by good explanation).
>> There may be times, however, where one
>> encoding is preferred over the other.
>>     
>
> Without examples, this is a meaningless phrase. And I think it is not 
> the encoding that is preferred, but we prefer one or the other way to 
> modify the upstream installation process. 
<sniped the example>
Good point.
>   
>> Following LFS's previous policy, if upstream distributes the manual
>>     
>
> Not sure if the reference to our previous setup (not policy, as we 
> couldn't change it!) is a good thing.
>
>   
Oh, sure we could...but uh...yeah. ;-) 

Thank you again for the detailed critique, suggestions and examples.  
You've been a great help.  I'll have another go at it using your text above.

-- DJ Lucas


-- 
This message has been scanned for viruses and
dangerous content, and is believed to be clean.




More information about the lfs-dev mailing list