After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 749162 - Documentation improvements and man pages
Documentation improvements and man pages
Status: RESOLVED OBSOLETE
Product: GStreamer
Classification: Platform
Component: gst-devtools
unspecified
Other All
: Normal enhancement
: git master
Assigned To: GStreamer Maintainers
GStreamer Maintainers
Depends on:
Blocks:
 
 
Reported: 2015-05-09 16:32 UTC by Emanuele Aina
Modified: 2018-11-03 11:06 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
validate: Go back to the validate dir after submodule init (738 bytes, patch)
2015-05-09 16:32 UTC, Emanuele Aina
committed Details | Review
validate: Reshape documentation (65.26 KB, patch)
2015-05-09 16:32 UTC, Emanuele Aina
committed Details | Review
validate: Generate man pages from the Docbook documentation (2.24 KB, patch)
2015-05-09 16:32 UTC, Emanuele Aina
none Details | Review

Description Emanuele Aina 2015-05-09 16:32:16 UTC
I started fixing some typos, then I started adding docbook tags where
appropriate and while I was at it I started editing some sentences to sound a
bit better. From there it all went downhill and in the end I reworked the
command line tools documentation to be able to generate man pages from it. :)
Comment 1 Emanuele Aina 2015-05-09 16:32:20 UTC
Created attachment 303148 [details] [review]
validate: Go back to the validate dir after submodule init
Comment 2 Emanuele Aina 2015-05-09 16:32:25 UTC
Created attachment 303149 [details] [review]
validate: Reshape documentation

Fix some errors, use more Docbook tags and split each command reference
in its own file.
Comment 3 Emanuele Aina 2015-05-09 16:32:30 UTC
Created attachment 303150 [details] [review]
validate: Generate man pages from the Docbook documentation
Comment 4 Emanuele Aina 2015-05-10 11:13:01 UTC
Ha ha, thanks for reassigning. Wrong `git bz` invocation from my shell history. %-)
Comment 5 Thibault Saunier 2015-05-10 17:14:47 UTC
Review of attachment 303148 [details] [review]:

OK
Comment 6 Thibault Saunier 2015-05-10 17:30:04 UTC
Thanks for that!

I try to build the man page but am getting:

make[3]: Entering directory '/home/thiblahute/devel/pitivi/1.0-uninstalled/gst-devtools/validate/docs/validate'
  MAN   gst-validate.1
warning: failed to load external entity "manpages/docbook.xsl"
cannot parse manpages/docbook.xsl

Not sure what is happening. 

Apart from that it looks good.
Comment 7 Thibault Saunier 2015-05-10 17:30:45 UTC
Review of attachment 303149 [details] [review]:

OK
Comment 8 Emanuele Aina 2015-05-10 21:22:28 UTC
(In reply to Thibault Saunier from comment #6)
> make[3]: Entering directory
> '/home/thiblahute/devel/pitivi/1.0-uninstalled/gst-devtools/validate/docs/
> validate'
>   MAN   gst-validate.1
> warning: failed to load external entity "manpages/docbook.xsl"
> cannot parse manpages/docbook.xsl
> 
> Not sure what is happening. 

Oops, I forgot to submit a local fix to gtk-doc. Done now, see bug #749210.

I'm not sure how to proceed. Should I just ignore gtk-doc errors instead of depending on an unreleased gtk-doc version or given that manpages are off by default it is ok?
Comment 9 Thibault Saunier 2015-05-11 06:47:56 UTC
(In reply to Emanuele Aina from comment #8)
> Oops, I forgot to submit a local fix to gtk-doc. Done now, see bug #749210.
> 
> I'm not sure how to proceed. Should I just ignore gtk-doc errors instead of
> depending on an unreleased gtk-doc version or given that manpages are off by
> default it is ok?

Any way you check it in configure.ac?
Comment 10 Thibault Saunier 2015-05-11 19:59:44 UTC
Attachment 303148 [details] pushed as 1286989 - validate: Go back to the validate dir after submodule init
Attachment 303149 [details] pushed as 2c3d0c9 - validate: Reshape documentation
Comment 11 Thibault Saunier 2015-05-11 20:00:44 UTC
Not closing until we have a check to generate the manpages.
Comment 12 Emanuele Aina 2015-05-13 06:22:50 UTC
The bug #749210 fix has been merged, but other than checking for the to-be-released gtk-doc version number (1.22.1) with pkg-config I don't think there are cleaner ways to check if the installed gtk-doc has it.
Comment 13 Stefan Sauer (gstreamer, gtkdoc dev) 2015-05-13 07:11:45 UTC
I would go forward with the change. The man-pages work on linux, I think one could also install an alias in the xmlcatalog to make it work on macosx.
Comment 14 Thibault Saunier 2015-05-13 08:49:19 UTC
(In reply to Emanuele Aina from comment #12)
> The bug #749210 fix has been merged, but other than checking for the
> to-be-released gtk-doc version number (1.22.1) with pkg-config I don't think
> there are cleaner ways to check if the installed gtk-doc has it.

That sounds clean to me. We should depend on 1.22.1 only if the user specified --enable-man though.
Comment 15 GStreamer system administrator 2018-11-03 11:06:49 UTC
-- GitLab Migration Automatic Message --

This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/gstreamer/gst-devtools/issues/13.