bundling manpages and documentation with piqi.rpm

[Motiejus Jakštys]

Hi Anton,

the initial RPM SPEC for piqi is there[1]. Now it has non-vanilla
/usr/bin/piqi and /usr/bin/piqic 0.6.3. Since package without
documentation is not a package, so I am thinking about adding some man
pages. I have two ideas:

1. Convert doc/*.md to Groff and bundle them as follows:
encodings.md -> piqi-encodings(1)
erlang.md -> piqi-erlang(1)
getopt.md -> piqi-getopt(1)
ocaml.md -> piqi-ocaml(1)
piqi.md -> piqi(1)*
piqi-rpc.md -> piqi-rpc(1)
piq.md -> piqi-piq(1) or piq(1)
protobuf.md -> piqi-protobuf(1)
README.md -> none
tools.md -> piqi(1)*

*: piqi.md is an overview, while tools.md looks like a proper
manpage for piqi(1). Not sure how to go about this.

2. tools.md -> piqi(1). Rest doc/*.md to HTML and bundle them in
/usr/share/doc/piqi/*.html, similar like you do in piqi.org/.

In both cases, piqic needs a manpage too. At least a minimal one. Maybe
it can be a short description with two references: piqi-ocaml and
piqi-erlang.

I would love (1) (since I love reading man pages), but the current docs
needs a bit of revamping to make it look good. (2) is easy - I can do it
just now.

What you think, what would you prefer?

[1]: https://github.com/Motiejus/piqi-rpm/

[Anton Lavrik]

Hi Motiejus,

I played with the piqi.spec and managed to get it work in my
environment. I'm going to comment on that separately. One thing that
is not exactly clear to me is whether the RPM spec and the packaging
scripts should be included in the main repository or maintained
separately. I guess it depends on the use case. For example, it is
probably too early to submit Piqi for inclusion into RPM-based distros
(let alone Debian), because the command-line API is not stable enough
and I don't like the idea of users being stuck with an old version for
years. However, the ability to package Piqi into .deb or .rpm is
useful regardless of that.

One important note about piqic. Starting from not-yet-announced
v0.6.3, piqi-erlang and piqi-rpc were removed from the main piqi
repository (including their documentation sections) and now maintained
in their own separate repositories
(https://github.com/alavrik/piqi-erlang and
https://github.com/alavrik/piqi-rpc). Their piqi compilers --
piqic-erlang and piqic-erlang-rpc have been rewritten in erlang and no
longer depend on piqic. Moreover, the piqic command no longer has
"piqic erlang" subcommand and soon will be renamed to piqic-ocaml.

For these reasons, there's no need to include piqic into the package
and documenting it wouldn't be very useful either.

Regarding man pages. I would go with option 2. tools.md will needs
some work, but information is there for the most part. Turning the
rest of documentation sections into manpages would take a lot more
effort and I don't think it is critical. Let's postpone it until
later. I like manpages too, but in this case, there are a lot of
benefits of keeping all documentation up-to-date and cross-linked in
one place on piqi.org

Anton

[Motiejus Jakštys]

On Mon, Apr 08, 2013 at 03:43:11AM -0500, Anton Lavrik wrote:
> Hi Motiejus,
>
> I played with the piqi.spec and managed to get it work in my
> environment.

Please let me know what changes were required so I can update piqi.spec.
I am it to work on Scientific Linux 6 and CentOS 6.4. Any other
distributions I should consider and test against?

> I'm going to comment on that separately. One thing that
> is not exactly clear to me is whether the RPM spec and the packaging
> scripts should be included in the main repository or maintained
> separately.

Separately. I cannot find a reference, but it is advised to do it that
way for both debian and rpm-based distros.

> I guess it depends on the use case. For example, it is
> probably too early to submit Piqi for inclusion into RPM-based distros
> (let alone Debian), because the command-line API is not stable enough
> and I don't like the idea of users being stuck with an old version for
> years.

I agree it is too early. First it will be in an ubuntu PPA and
opensuse's Open Build Service[1]. Then we shall see.

> However, the ability to package Piqi into .deb or .rpm is useful
> regardless of that.

Users can obtain RPMs or DEBs from auxiliary sources like PPA or OBS,
which do not have such strong consistency and "stability" requirements.
I think users who will frequently use piqi will want to install these
packages for convenience from these repos.

> One important note about piqic. Starting from not-yet-announced
> v0.6.3, piqi-erlang and piqi-rpc were removed from the main piqi
> repository (including their documentation sections) and now maintained
> in their own separate repositories
> (https://github.com/alavrik/piqi-erlang and
> https://github.com/alavrik/piqi-rpc). Their piqi compilers --
> piqic-erlang and piqic-erlang-rpc have been rewritten in erlang and no
> longer depend on piqic. Moreover, the piqic command no longer has
> "piqic erlang" subcommand and soon will be renamed to piqic-ocaml.

Yes, I found that out already.

IMO piqic-erlang, piqic-erlang-rpc should not have corresponding RPM/DEB
repositories, they should be used the way they are used now via rebar
dependencies.

> For these reasons, there's no need to include piqic into the package
> and documenting it wouldn't be very useful either.

Sure.

> Regarding man pages. I would go with option 2. tools.md will needs
> some work, but information is there for the most part. Turning the
> rest of documentation sections into manpages would take a lot more
> effort and I don't think it is critical. Let's postpone it until
> later. I like manpages too, but in this case, there are a lot of
> benefits of keeping all documentation up-to-date and cross-linked in
> one place on piqi.org

Good. I will go with the option 2 now.

I am in process of creating the debian package; then I will put the docs
and man pages, and take care of piqi-erlang integration with a
system-wide piqi binary.

Thanks for merging the DESTDIR stuff. My patchwork will become less
involved when you release 0.6.4. :-)

Motiejus

[1]: https://build.opensuse.org/