Bug 17379 - Add a man page for koha-passwd
Summary: Add a man page for koha-passwd
Status: CLOSED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: Command-line Utilities (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement (vote)
Assignee: Lucio Moraes
QA Contact: Katrin Fischer
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2016-09-29 19:53 UTC by Magnus Enger
Modified: 2023-12-28 20:42 UTC (History)
7 users (show)

See Also:
Change sponsored?: ---
Patch complexity: Trivial patch
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:
22.11.00


Attachments
Bug 17379 - Add a man page for koha-passwd (2.24 KB, patch)
2016-10-24 08:26 UTC, Lucio Moraes
Details | Diff | Splinter Review
Bug 17379 - Add a man page for koha-passwd (2.33 KB, patch)
2016-10-24 21:50 UTC, Lucio Moraes
Details | Diff | Splinter Review
Bug 17379 - Add a man page for koha-passwd (2.29 KB, patch)
2016-10-24 23:50 UTC, Lucio Moraes
Details | Diff | Splinter Review
Bug 17379 - Add a man page for koha-passwd (2.41 KB, patch)
2016-10-25 06:49 UTC, Magnus Enger
Details | Diff | Splinter Review
Bug 17379 - Add a man page for koha-passwd (2.29 KB, patch)
2016-10-25 20:57 UTC, Lucio Moraes
Details | Diff | Splinter Review
Bug 17379 - Add a man page for koha-passwd (2.35 KB, patch)
2016-11-30 20:39 UTC, Mika
Details | Diff | Splinter Review
Bug 17379: Add a man page for koha-passwd (2) (713 bytes, patch)
2022-09-21 12:02 UTC, Mason James
Details | Diff | Splinter Review
Bug 17379: Add a man page for koha-passwd (2) (719 bytes, patch)
2022-09-21 23:03 UTC, David Nind
Details | Diff | Splinter Review
Bug 17379: Add a man page for koha-passwd (2.40 KB, patch)
2022-10-08 10:38 UTC, Katrin Fischer
Details | Diff | Splinter Review
Bug 17379: Add a man page for koha-passwd (2) (777 bytes, patch)
2022-10-08 10:38 UTC, Katrin Fischer
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Magnus Enger 2016-09-29 19:53:10 UTC
The koha-passwd utility was added by bug 13143, but no corresponding man page was added. That should be fixed.
Comment 1 Lucio Moraes 2016-10-24 08:26:06 UTC Comment hidden (obsolete)
Comment 2 Magnus Enger 2016-10-24 09:24:16 UTC Comment hidden (obsolete)
Comment 3 Magnus Enger 2016-10-24 09:34:44 UTC Comment hidden (obsolete)
Comment 4 Lucio Moraes 2016-10-24 21:16:40 UTC Comment hidden (obsolete)
Comment 5 Lucio Moraes 2016-10-24 21:50:12 UTC Comment hidden (obsolete)
Comment 6 Lucio Moraes 2016-10-24 21:54:56 UTC Comment hidden (obsolete)
Comment 7 Lucio Moraes 2016-10-24 23:50:09 UTC Comment hidden (obsolete)
Comment 8 Magnus Enger 2016-10-25 06:49:14 UTC Comment hidden (obsolete)
Comment 9 Jonathan Druart 2016-10-25 08:42:29 UTC
Comment on attachment 56826 [details] [review]
Bug 17379 - Add a man page for koha-passwd

Review of attachment 56826 [details] [review]:
-----------------------------------------------------------------

::: debian/docs/koha-passwd.xml
@@ +4,5 @@
> +    <productname>Koha</productname> is the first free software library automation package.
> +    <author>
> +        <personname>
> +            <firstname>Lucio</firstname>
> +            <surname>Moraes</surname>

I have always thought that the AUTHOR section was for the name of the developer and not the one who wrote the doc.
Actually it seems that this section is for both. I'd prefer to see the 2 names: you and Mason (see 78a6f7b0e7).
However http://man7.org/linux/man-pages/man7/man-pages.7.html says:
  "Use of an AUTHORS section is strongly discouraged."
So the other possibility is to simply remove it, I do not have a strong opinion.

Someone else maybe?
Comment 10 Magnus Enger 2016-10-25 08:51:31 UTC
(In reply to Jonathan Druart from comment #9)
>   "Use of an AUTHORS section is strongly discouraged."
> So the other possibility is to simply remove it, I do not have a strong
> opinion.
> 
> Someone else maybe?

Running this: 

  grep -A 3 "<author" debian/docs/*

shows to varieties. The most common one is:

<author>
  <orgname>The Koha Community</orgname>
  <uri>http://koha-community.org/</uri>
</author>

But there are also some where Robin has added his name: 

    <author>
        <personname>
            <firstname>Robin</firstname>
            <surname>Sheat</surname>

I would vote for the first one, I think.
Comment 11 Lucio Moraes 2016-10-25 20:32:20 UTC
Hi,
I think this should be better

<author>
  <orgname>The Koha Community</orgname>
  <uri>http://koha-community.org/</uri>
</author>

any thoughts? should I change?
thanks
Comment 12 Lucio Moraes 2016-10-25 20:57:07 UTC Comment hidden (obsolete)
Comment 13 Mika 2016-11-30 20:39:27 UTC
Created attachment 57848 [details] [review]
Bug 17379 - Add a man page for koha-passwd

Adding a manpage for the koha-passwd utility.

To test:
1) Run these commands and look at the formatted man page:
$xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/docbook.xsl \
 debian/docs/koha-passwd.xml
2)$man -l koha-passwd.8

3) Make sure this test passes:  $prove -v xt/verify-debian-docbook.t

Signed-off-by: Mika Smith <mikasmith@catalyst.net.nz>
Comment 14 Jonathan Druart 2016-12-27 17:11:58 UTC
The Author part is displayed like:

"""
AUTHOR
       Mason James
       The Koha Community
           Author
"""

What is this last "Author" line?

(In reply to Jonathan Druart from comment #9)
> However http://man7.org/linux/man-pages/man7/man-pages.7.html says:
>   "Use of an AUTHORS section is strongly discouraged."

Still do not want to follow the man page of man? :)
Comment 15 Magnus Enger 2017-02-17 06:33:28 UTC
Removing the AUTHOR section from all man pages is probably out of scope for the current bug report? We could do that as a separate bug.
Comment 16 Jonathan Druart 2017-02-17 09:08:18 UTC
(In reply to Magnus Enger from comment #15)
> Removing the AUTHOR section from all man pages is probably out of scope for
> the current bug report? We could do that as a separate bug.

Absolutely not what I asked, just waiting for 1 line removal.
Comment 17 Mason James 2022-09-21 12:02:42 UTC
Created attachment 140815 [details] [review]
Bug 17379: Add a man page for koha-passwd (2)
Comment 18 Mason James 2022-09-21 12:03:19 UTC
(In reply to Jonathan Druart from comment #16)
> (In reply to Magnus Enger from comment #15)
> > Removing the AUTHOR section from all man pages is probably out of scope for
> > the current bug report? We could do that as a separate bug.
> 
> Absolutely not what I asked, just waiting for 1 line removal.

hi Jonathan, i've made the 1 line removal.
Comment 19 David Nind 2022-09-21 23:03:12 UTC
Created attachment 140838 [details] [review]
Bug 17379: Add a man page for koha-passwd (2)

Signed-off-by: David Nind <david@davidnind.com>
Comment 20 David Nind 2022-09-21 23:05:07 UTC
Testing notes (using KTD):

1. For whatever reason, the man page software is not installed in KTD (see https://gitlab.com/koha-community/koha-testing-docker/-/issues/155). Installed with: apt-get install man-db

2. man koha-passwd
   ==> No manual entry for koha-passwd

3. Apply the patches.

4. I tried to follow the test plan, but was not able to update the man page output (see note below).

5. I reviewed the source file (debian/docs/koha-passwd.xml) and can confirm that the required change was made.

6. Have signed off, as I'm assuming that the build process will take care of correctly producing the man pages once the change is pushed to master.

Note: I'm not sure that the steps in the test plan to produce the man page is correct - they didn't work for me anyway. I tried shutting down KTD, restarting, and apt-get install man-db again - flush_memcached and restart_all wasn't sufficient, and even then it outputted the "old" man page without the author line removed. See steps 5 and 6.
Comment 21 Katrin Fischer 2022-10-08 10:36:46 UTC
I also installed apt-get install man-db.
And I did a reset_all in hope that the files would get copied to the right place.
Also did a man koha-common.
I am not sure what worked :( But: man koha-passwd now shows the help for me.
Comment 22 Katrin Fischer 2022-10-08 10:38:06 UTC
Created attachment 141540 [details] [review]
Bug 17379: Add a man page for koha-passwd

Adding a manpage for the koha-passwd utility.

To test:
1) Run these commands and look at the formatted man page:
$xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/docbook.xsl \
 debian/docs/koha-passwd.xml
2)$man -l koha-passwd.8

3) Make sure this test passes:  $prove -v xt/verify-debian-docbook.t

Signed-off-by: Mika Smith <mikasmith@catalyst.net.nz>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 23 Katrin Fischer 2022-10-08 10:38:10 UTC
Created attachment 141541 [details] [review]
Bug 17379: Add a man page for koha-passwd (2)

Signed-off-by: David Nind <david@davidnind.com>

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 24 Tomás Cohen Arazi 2022-10-11 13:23:29 UTC
Pushed to master for 22.11.

Nice work everyone, thanks!