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 684719 - Man pages for gnc-fq-* perl scripts
Man pages for gnc-fq-* perl scripts
Status: RESOLVED FIXED
Product: GnuCash
Classification: Other
Component: Documentation
git-master
Other All
: Normal enhancement
: future
Assigned To: Frank H. Ellenberger
gnucash-documentation-maint
Depends on:
Blocks:
 
 
Reported: 2012-09-24 14:40 UTC by Frank H. Ellenberger
Modified: 2018-06-29 23:10 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Makefile.am_gnc-fq_man-pages.patch (612 bytes, patch)
2012-09-24 14:40 UTC, Frank H. Ellenberger
committed Details | Review
gnc-fq-dump.1 (4.28 KB, text/plain)
2012-09-24 14:45 UTC, Frank H. Ellenberger
  Details
gnc-fq-helper.1 (6.69 KB, text/plain)
2012-09-24 14:46 UTC, Frank H. Ellenberger
  Details

Description Frank H. Ellenberger 2012-09-24 14:40:07 UTC
Created attachment 225069 [details] [review]
Makefile.am_gnc-fq_man-pages.patch

In my youth almost everybody would have denied to run a program, if there were no man page for it.

with the appending patch I was able to extract the pod content from src/quote/gnc-fq-* files.

It is still rudimemtary, but the question is, how to continue.

As you can see in http://lists.gnucash.org/logs/2012/09/2012-09-24.html#T09:48:18
Derek dislikes the to depend on perldoc in the build system.

So I see 3 options:
a) make it optional in the build system.
b) I improve the files to current standards, run locally pod2man and attach the resulting files to (what is the right place for prepared man pages?)

c) In theory IIRC also doxygen understands perl and can create man pages, but that needs further research.


Opinions?
Comment 1 Frank H. Ellenberger 2012-09-24 14:45:22 UTC
Created attachment 225070 [details]
gnc-fq-dump.1

gnc-fq-dump man page
Comment 2 Frank H. Ellenberger 2012-09-24 14:46:40 UTC
Created attachment 225071 [details]
gnc-fq-helper.1

gnc-fq-helper man page
Comment 3 Frank H. Ellenberger 2012-09-24 16:50:18 UTC
r22424 is a interim presentation of dereks suggestion with static files in doc.
Comment 4 Geert Janssens 2012-10-22 13:38:20 UTC
> 09:48:18 <fell> warlord: with "pod2man $< > $@" in the makefile I can extract man pages for gnc-fq-*
> 09:54:28 <warlord> fell: I don't think we want to depend on pod2man existing during the build.
> 09:59:53 <fell> Ok, I will it not commit. I will put it in bugzilla for discussion.
> 10:00:22 <warlord> for example, I dont know if pod2man is available in the default Win32 build.
> 10:00:46 <warlord> considering those apps dont change much, why not just run pod2man manually and check in the resulting manpages?
> 10:00:50 <fell> It is part of perldoc
> 10:01:44 <warlord> is that a current build dep?
> 10:03:10 <fell> It is a very basic part of perl, because all of their docs are made by it.
> 10:08:26 <warlord> Sure, but I don't think perl is part of our build system, is it? I dont think we *need* perl to build gnucash currently.

Perl is part of our Windows32 build system and it *is* used in the build scripts. Mostly for regular expression based replacements. There is even a perldoc command present by default. This all comes as part of the default msys (or is it msys-dtk ?) installation we do. The perl version installed that way is rather old though: 5.6.1.

Unfortunately, there is no pod2man installed by default. Perhaps that's due to the old version ? It means we can't just depend on pod2man for the man page generation, unless we figure out how to get it installed by default.

(In reply to comment #0)
> So I see 3 options:
> a) make it optional in the build system.
> b) I improve the files to current standards, run locally pod2man and attach the
> resulting files to (what is the right place for prepared man pages?)
> 
> c) In theory IIRC also doxygen understands perl and can create man pages, but
> that needs further research.
> 
> 
> Opinions?

Option a can work. I don't think many Windows users will be interested in man pages. So we could create man pages on the other platforms and just skip it on Windows. If we find a way to get the man pages on Windows anyway, I'd prefer that though.

I like option b a lot less. If the man pages aren't autogenerated, we sooner or later will end up with different perlpod and manpage versions for the packages.

Option c might be nice. Alternatively, you can also try to figure out if there is an easy way to get pod2man installed in the windows build environment. That might be easier since we have perl available already.
Comment 5 Geert Janssens 2013-02-28 11:52:30 UTC
Just to add to this: I have started work to improve the windows build setup and configuration. This should give us among others a more recent version of perl during development. It is my hope that it will also give us the missing pod2man tool (from last time I checked, it believe it does).

I'll get back to this when I know more.
Comment 6 Geert Janssens 2014-05-21 10:00:21 UTC
Update: the more recent msys environment we are now using to build the windows packages ships perl 5.8. This perl version does contain the required pod2man.

I have also checked other platforms:
- OS X (10.6.8) has pod2man on my system.
- Fedora 20 has pod2man. If I try to remove it it more or less removes half of my system.

So I would conclude pod2man can be assumed to be available if perl >= 5.8 is present. I think you can proceed with adding makefile rules to generate the man pages. We should only determine still where they should get installed (which man directory).
Comment 7 Geert Janssens 2014-09-02 21:04:51 UTC
Comment on attachment 225069 [details] [review]
Makefile.am_gnc-fq_man-pages.patch

With pod2man now being available by default in all environments we use, I have pushed Frank's original patch to master.

Thanks for the patch !
Comment 8 John Ralls 2018-06-29 23:10:54 UTC
GnuCash bug tracking has moved to a new Bugzilla host. This bug has been copied to https://bugs.gnucash.org/show_bug.cgi?id=684719. Please update any external references or bookmarks.