tech-pkg archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

Fixing catman pages



Until now, pkgsrc has not had support for catman pages on at least
SunOS, and probably HP-UX and others too.  There are two primary
issues:

 - They use a suffix based on the section, i.e. "cat1/foo.1", whereas
   BSD hardcodes every catman page with a .0 suffix regardless of the
   section.  This means man(1) cannot find the catman page, and so
   tries to render the original instead.

 - The SVR4 nroff(1) does not support the BSD mandoc macros, and so
   displaying the original man page misses lots of formatting, making
   the resulting page mostly unreadable.

I have a number of changesets which address both these issues, split
into two bodies of work:

 #1: Use mdocml as the tool replacement for nroff.
 =================================================

  Some packages which generate catman pages ('pkgin', for example) add
  a USE_TOOLS dependency on nroff, which currently will pull in groff.

  Whilst this works, it is not ideal as groff has many dependencies,
  and when adding catman support to e.g. devel/tradcpp we run into
  circular dependency issues.

  To fix this, two changesets are required.  First, allow mdocml and
  groff to co-exist, so that 'USE_TOOLS= groff nroff' will work
  correctly.  This involves renaming some of mdocml's files:

    
https://github.com/joyent/pkgsrc/commit/1e43db1ed16b8d232001ec68f237a791afdff473

  Secondly, use mdocml for USE_TOOLS=nroff:

    
https://github.com/joyent/pkgsrc/commit/de6ecbe53c452369475e9058542666bee864c3f2

  This should have benefits regardless of catman issues, as mdocml is
  much smaller than groff and is BSD licensed.

 #2: Add catman section support
 ==============================

  First we add infrastructure support for catman pages to have a named
  suffix.  This introduces a CATMAN_SECTION_SUFFIX variable which
  determines whether to append the section suffix or the '.0' default:

    
https://github.com/joyent/pkgsrc/commit/1ff2bdd1a4e8d015dd0c1185f615208f20c29234

  This diff also includes SunOS modifications to bootstrap-mk-files to
  enable MKCATPAGES by default and support the section suffix, and
  also has the necessary changes to pkg_install for bootstrap to
  complete successfully.

  The final diff is:

    
https://github.com/joyent/pkgsrc/commit/f6d5ebdde3b37511505ffcb00cca772a4408224e

  which fixes the remaining 19 packages that generate catman pages.
  One of the included changes is to revert the fix for PR#42533,
  however I believe the correct fix for that bug is to change HP-UX to
  match what I have done for SunOS above, so that mdocml can generate
  the catman page on that system.

It would be great to get these changes in for 2013Q3 so please review
accordingly.  These changes have been tested in SunOS bulk builds, and
should mostly be NOPs on other platforms, i.e. where there is a
BSD-compatible nroff already installed.

Thanks,

-- 
Jonathan Perkin  -  Joyent, Inc.  -  www.joyent.com


Home | Main Index | Thread Index | Old Index