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

[Norm Jacobs]

On 10/9/19 1:57 PM, Tim Mooney wrote:


 default mangler.man.stability 
"pass-through volatile">


This transform adds 'manger.man.stability="pass-through volatile"' to 
the man page entries in the package manifest.  Those attributes are 
consumed by the userland-mangler, which post-processes the files being 
packaged prior to packaging them. This specific attribute specifies the 
Solaris interface taxonomy of the interface described in the man page.  
If you read the standards(5) man page, it describes Solaris interface 
taxonomy. Virtually all of the open source software that was in Solaris 
had a taxonomy that let folks know that it was subject to incompatible 
change more or less at any time because Solaris was at the mercy of the 
upstream.  I'm not sure what level of commitment to interface taxonomy 
OI adopts, so it might make sense to just drop this information in OI.


    -Norm


___
oi-dev mailing list
oi-dev@openindiana.org
https://openindiana.org/mailman/listinfo/oi-dev

Re: [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:

 \
 ??? default facet.doc.man true>
 \
 ??? 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: default 
mangler.man.stability uncommitted>

defaults:187:# Avoid mangling compressed man pages
defaults:188: default 
mangler.bypass true>

docs:26:# man pages
docs:27: \
docs:28:default facet.doc.man all>
docs:30: \
docs:31:default facet.doc.man all>
docs:70: 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.

 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.moo...@ndsu.edu
Enterprise Computing & Infrastructure /
Division of Information Technology/701-231-1076 (Voice)
North Dakota State University, Fargo, ND 58105-5164

___
oi-dev mailing list
oi-dev@openindiana.org
https://openindiana.org/mailman/listinfo/oi-dev