[Xapian-tickets] [Xapian] #569: omindex --help text for -F misleading

[Xapian]

#569: omindex --help text for -F misleading
--------------------+-------------------------------------------------------
 Reporter:  catkin  |       Owner:  olly    
     Type:  defect  |      Status:  assigned
 Priority:  normal  |   Milestone:  1.3.0   
Component:  Omega   |     Version:  1.2.5   
 Severity:  normal  |    Keywords:          
Blockedby:          |    Platform:  All     
 Blocking:          |  
--------------------+-------------------------------------------------------

Old description:

> From the omindex man page:
>
> -F, --filter=TYPE:CMD
>     process files with MIME Content-Type TYPE using command CMD, which
> should produce UTF-8 text on stdout e.g. -Fapplica‐tion/octet-
> stream:'strings -n8
>
> This could be understood to mean that omindex examines files to determine
> their MIME type (I understood it that way) but from Olly's posting,
> subject "Re: [Xapian-discuss] Tika 0.8 failure rates", date 5oct11:
>
> By default, omindex currently uses a list of extension->MIME
> content-type mappings, and only consults the magic library for
> extensions it doesn't know.  So any file with a .doc extension will be
> considered as application/msword (unless you run omindex with
> '--mime-type=doc:').
>
> A note about this could be added to the omindex man page and referenced
> from the -F and -M options descriptions.

New description:

 From the omindex man page:

 {{{
 -F, --filter=TYPE:CMD
     process files with MIME Content-Type TYPE using command CMD, which
 should produce UTF-8 text on stdout e.g. -Fapplica‐tion/octet-
 stream:'strings -n8
 }}}

 This could be understood to mean that omindex examines files to determine
 their MIME type (I understood it that way) but from Olly's posting,
 subject "Re: [Xapian-discuss] Tika 0.8 failure rates", date 5oct11:

 By default, omindex currently uses a list of extension->MIME
 content-type mappings, and only consults the magic library for
 extensions it doesn't know.  So any file with a .doc extension will be
 considered as application/msword (unless you run omindex with
 '--mime-type=doc:').

 A note about this could be added to the omindex man page and referenced
 from the -F and -M options descriptions.

--

Comment(by olly):

 Looking into this, I'm not really sure how to improve this - the option
 right above -F makes it pretty clear that the MIME type can comes from the
 file extension:

 {{{
   -M, --mime-type=EXT:TYPE map file extension EXT to MIME Content-Type
 TYPE
                            (empty TYPE removes any MIME mapping for EXT)
 }}}

 And if we add too much verbiage here, it stops being so useful for quick
 reference and ends up just duplicating the main documentation.

 Thoughts?

-- 
Ticket URL: <http://trac.xapian.org/ticket/569#comment:2>
Xapian <http://xapian.org/>
Xapian