[oi-dev] what transforms and/or actuators for man pages?

[Michal Nowak]

Hi Tim.

On 10/08/19 11:34 PM, Tim Mooney wrote:
> 
> What are the recommended transforms to include in a component's .p5m file
> for man pages?
> 
> The "Packaging and Delivering Software with IPS" guide has an example
> (chapter 4, pages 27-28) of:
> 
> <transform dir file link hardlink path=opt/.+/man(/.+)? -> \
>      default facet.doc.man true>
> <transform file path=opt/.+/man(/.+)? -> \
>      add restart_fmri svc:/application/man-index:default>
> 
> The /usr/share/pkg/transform/documentation file has the same thing, but
> for /usr/share/man, rather than the example above, for /opt.
> 
>

Did you look into transforms/ of the oi-userland project?

It holds transform rules for every processed p5m file:

  newman   oi/hipster  ~  ws  oi-userland  transforms  ggrep -Rwn man
defaults:185:<transform file path=usr.*/man/.+ -> default 
mangler.man.stability uncommitted>
defaults:187:# Avoid mangling compressed man pages
defaults:188:<transform file path=usr.*/man/.+\.(Z|bzip2|gz|xz)$ -> 
default mangler.bypass true>
docs:26:# man pages
docs:27:<transform dir file link hardlink path=usr.*/man/.+$ -> \
docs:28:    default facet.doc.man all>
docs:30:<transform dir path=usr.*/man$ -> \
docs:31:    default facet.doc.man all>
docs:70:<transform dir file link hardlink facet.doc.man=all -> delete 
facet.doc all>

> The actual .p5m files in oi-userland use a wide variety of transforms
> for man pages, such as
> 
> <transform file path=usr/share/man/(man3/.+$) -> set action.hash %<\1> >
> <transform file path=usr.*/man/.+ -> default mangler.man.stability 
> uncommitted>
> 
> or
> 
> <transform file path=usr.*/man/.+ -> default mangler.man.stability 
> Uncommitted>
> 
> or
> 
> <transform file path=usr.*/man/.+ -> default mangler.man.stability 
> volatile>
> 
> or
> 
> <transform file path=usr.*/man/.+ -> default mangler.man.stability 
> "pass-through volatile">
> 

In userland, I believe that all/most the mangler.man.stability 
transforms, other than the default one setting man page stability to 
"uncommitted", should be removed because we can't really guarantee 
stability as userland is for the most part a set of third-party open 
source packages we don't control and can't promise anything (see my 
reasoning here 
https://github.com/OpenIndiana/oi-userland/pull/5060#pullrequestreview-246364150). 
Also see the tools/userland-mangler script.

> I don't see any current .p5m files that use the restart_fmri for OI's
> service svc:/system/update-man-index:default , which I'm assuming is
> equivalent to the svc:/application/man-index:default from the example.

update-man-index service is not restarted on man page being added to 
/usr/share/man/ though `whatis` knows about the new man page... so, I 
admit I don't understand this part of the process.

> 
> So, what are best practices for man page transforms for OI?
> 
> Thanks!
> 
> Tim

Michal