[Bug 1003962] New: RPM scriptlet -p option not documented

[Red Hat Bugzilla]

https://bugzilla.redhat.com/show_bug.cgi?id=1003962

Bug ID: 1003962
           Summary: RPM scriptlet -p option not documented
           Product: Fedora Documentation
           Version: devel
         Component: rpm-guide
          Assignee: [e-mail]
          Reporter: [e-mail]
        QA Contact: [e-mail]
                CC: [e-mail], [e-mail],
                    [e-mail]

The fedora RPM guide does not document the -p option that can be passed to the
RPM scriptlets.  It should probably be located here
http://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_...,
but I looked through the entire guide and couldn't find it.

The only only place I could find it documented is here
https://fedoraproject.org/wiki/Packaging:ScriptletSnippets, but what it says is
wrong.  It says:

"The basic syntax is similar to the %build, %install, and other sections of the
rpm spec file. The scripts support a special flag, -p which allows the
scriptlet to invoke a single program directly rather than having to spawn a
shell to invoke the programs. (ie: %post -p /sbin/ldconfig)"

A more accurate description is:

"The basic syntax is similar to the %build, %install, and other sections of the
rpm spec file.

The scripts support a special flag, -p which specifies the interPreter that
should be used to run the script (the default is /bin/sh).  Sometimes the -p
option is used with no body in order to run a single command directly rather
than having to spawn a shell to invoke the programs (i.e. %post -p
/sbin/ldconfig).  Note that this form requires that there be nothing but white
space (not even comments) until the next section begins."

[Bug 1003962] RPM scriptlet -p option not documented

[Red Hat Bugzilla]

https://bugzilla.redhat.com/show_bug.cgi?id=1003962

Jamie Duncan  changed:

What    |Removed                     |Added
----------------------------------------------------------------------------
              Flags|                            |needinfo?(bcotton+fedora@gm
                   |                            |ail.com)

--- Comment #1 from Jamie Duncan  ---
Ben

I'm happy to help out with this one, if we can get it moving to a quick fix.

Thanks,

Jamie Duncan

[Bug 1003962] RPM scriptlet -p option not documented

[Red Hat Bugzilla]

https://bugzilla.redhat.com/show_bug.cgi?id=1003962

Petr Kovar  changed:

What    |Removed                     |Added
----------------------------------------------------------------------------
          Component|rpm-guide                   |packager-guide
           Assignee|[e-mail]    |[e-mail]

--- Comment #2 from Petr Kovar  ---
Moving to the Packager's Guide.

[Bug 1003962] RPM scriptlet -p option not documented

[Red Hat Bugzilla]

https://bugzilla.redhat.com/show_bug.cgi?id=1003962

Jared Smith  changed:

What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |[e-mail]

--- Comment #3 from Jared Smith  ---
I've added a patch to the RPM Guide to add that clarification.  The new
information should be part of git commit
cc44b49e0977e4f50ae09f48b15b8367c59331de.  The new information should show up
in the guide the next time the document is rebuilt.

Just as an FYI, the RPM Guide is fairly old and not being actively maintained
like it should be.  There's a new effort underway to take the most important
information from the RPM Guide and build a Packager's Guide, but that guide
doesn't yet go into any detail on scripts.  Petr Kovar reassigned this bug to
him, so hopefully he'll add something to the Packager's Guide about scriptlets.

[Bug 1003962] RPM scriptlet -p option not documented

[Red Hat Bugzilla]

https://bugzilla.redhat.com/show_bug.cgi?id=1003962

--- Comment #4 from [e-mail] ---
Thanks for adding the patch.

Why was the decision made to create a new guide rather than just renaming or
updating the old guide?

Also, wouldn't it make more sense to start by documenting the spec file
syntax/"language" as part of the rpm-build rpm?  It seems like the problem is
that there's a tool, rpmbuild, that processes a syntax, spec files, that isn't
documented or standardized.

In my mind, a "guide" is high level documentation that is very nice to have,
but should be based on my low level documentation.  The low level documentation
for the tool, rpmbuild, exists, but we're missing the low level documentation
for what the tool processes, spec files.

Just some thoughts.  Thanks for the help.

[Bug 1003962] RPM scriptlet -p option not documented

[Red Hat Bugzilla]

https://bugzilla.redhat.com/show_bug.cgi?id=1003962

--- Comment #5 from Jared Smith  ---
(In reply to daniel.neuberger from comment #4)
> Thanks for adding the patch.

You're most welcome.
> Why was the decision made to create a new guide rather than just renaming or
> updating the old guide?

In short, for a couple of reasons.  The first reason is that the exiting guide
is a bit overwhelming to new packagers, and we really wanted to have a guide
focused on helping novice packagers get up to speed.

The second reason is the simple fact that updating the existing guide would be
an enormous undertaking, and nobody has volunteered to step up and do the work.
 There's nothing that says we can't have two guides, we just need help to do
the work.
> Also, wouldn't it make more sense to start by documenting the spec file
> syntax/"language" as part of the rpm-build rpm?  It seems like the problem
> is that there's a tool, rpmbuild, that processes a syntax, spec files, that
> isn't documented or standardized.

It makes sense to me, but I'm just a volunteer, and I don't have either the
time or inclination to dive into documenting every detail at that level.  Until
someone volunteers to do the work or gets asked to do it as part of their day
job, it's just wishes and dreams.

One of the unfortunate truths is that writing documentation isn't sexy, and in
open source communities, it often doesn't get the attention that developing new
code does.  As with everything else in open source, we either have to scratch
the itch ourselves, pay someone to scratch it for us, or find a way to convince
someone else that it's their itch.

[Bug 1003962] RPM scriptlet -p option not documented

[Red Hat Bugzilla]

https://bugzilla.redhat.com/show_bug.cgi?id=1003962

--- Comment #6 from [e-mail] ---
Thanks Jared for all the info.  Unfortunately, I can't undertake the complete
task myself either (at least not right now).  I will do my best to help push
things in the right direction and contribute bits and pieces as I go along with
my work.

[Bug 1003962] RPM scriptlet -p option not documented

https://bugzilla.redhat.com/show_bug.cgi?id=1003962

Petr Kovar  changed:

What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |[e-mail]
          Component|packager-guide              |doc-Packagers_Guide
            Version|devel                       |7.4
           Assignee|[e-mail]           |[e-mail]
            Product|Fedora Documentation        |Red Hat Enterprise Linux 7
   Target Milestone|---                         |rc
         QA Contact|[e-mail] |[e-mail]
                   |.org                        |

--- Comment #7 from Petr Kovar  ---
The Fedora packager guide has been deprecated in favor of
https://github.com/redhat-developer/rpm-packaging-guide/.

Moving this bug to the RHEL version of redhat-developer/rpm-packaging-guide to
investigate if this still is a relevant issue.