Re: mandocdb: handle formatted manuals

[Ingo Schwarze <schwarze@usta.de>]

Hi Kristaps,

Kristaps Dzonsons wrote on Sat, Nov 26, 2011 at 01:01:57PM +0100:
> Ingo Schwarze wrote:

>> Currently, we have
>>
>>   recno ->  filename \0 section \0 title \0 arch \0 description \0
>>
>> Given that the description will typically be dozens of characters,
>> i don't think encoding the file type in a single byte with a set
>> of #defines is worth the obfuscation, so i'd just make that
>>
>>   recno ->  type \0 filename \0 section \0 title \0 arch \0 description \0
>>
>> where type = ( mdoc | man | cat ).

> That's exactly what I had in mind.  I think it's pretty clear which
> areas will need the offset calculation.  mandocdb(8) will also need
> to be updated -- come to think of it, it already needs updating with
> the new types.  Do you want to do that, or shall I?

Feel free to, and/or use all or part of the suggestions
i just sent in a parallel mail (that draft was rotting here
for a week, now i sent it).

>> I don't think any other information is required in the index.
>>
>> However, you planned to check endian-neutrality, right?

> Yes, although this is purely a mechanical check (it is absolutely
> necessary).  I'll do this when your above changes have been checked
> in so we avoid clobbering each other.
> 
> Til then, I'll work almost exclusively with man.cgi and manup.  By
> the way, any suggestions for manup's name?  Just "man up" and tell
> me. ;)

To avoid the NIH syndrom, this is what i find on one a Linux
system i have access to:

  NAME
       catman - create or update the pre-formatted manual pages

  SYNOPSIS
       catman [-dhV] [-M path] [-C file] [section] ...

I think we should not implement the -d, -h, and -V options, but
the -M argument is great.  On OpenBSD, we would use man.conf(5)
by default, and elsewhere, maybe manpath(1) - i haven't really
looked into the latter yet, but clearly don't like it, it's even
worse than man.conf(5) with respect to overengineering, but
probably there is nothing for us to decide.  Maybe we don't need
the section arguments either, just use the sections found on disk.
If we ever get bored, we can add -C to mandocdb(8), apropos(1),
and catman(8).

In summary, the tool is going to be similar enough that we don't
need to invent a new name.  That's not to say that i consider the
name catman(8) to be well-chosen, but at least it's an established
name for the thing.  Or what do you think?

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv