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

[Tim Mooney]

In regard to: Re: [oi-dev] what transforms and/or actuators for man pages?,...:

> 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?

No, in fact I didn't know about them until now!  Thanks for pointing
me at them.

> 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>

Sooo... there's really no point me adding transforms for locale or man
pages or /usr/share/gtk-doc to any component I update, because there's
a large set of suitable defaults for most stuff in the transforms/*
files that get automatically applied.

I had no idea.  I've been content to focus on updates and rebuilds, and if
'gmake publish' x 3 works and testing looks OK, I've treated the 'publish'
target as a black box.  I guess I need to spend more time looking at
what's going on behind the scenes.

>> <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 will follow your example and do the same if I touch a third-party
component, but what about other transforms in the .p5m file, like
the gtk-doc transforms or the locale transform?  If they are the
default transform, rather than something special for a particular package,
should they be removed too?

Thanks much Michal!  The info you provided filled in a large gap in
information that I didn't even know I was missing.

Tim
-- 
Tim Mooney                                             Tim.Mooney at ndsu.edu
Enterprise Computing & Infrastructure /
Division of Information Technology    /                701-231-1076 (Voice)
North Dakota State University, Fargo, ND 58105-5164