GNOME Bugzilla – Bug 667340
gnome-boxes should ship a manpage
Last modified: 2018-01-11 09:51:55 UTC
This was requested as part of fedora review process https://bugzilla.redhat.com/show_bug.cgi?id=770152#c8 Totem for example has one.
For UIs, its the Help pages that are more relevant but having a manpage would be nice too.
Created attachment 324393 [details] Simple manpage for gnome-boxes (fixed)
(In reply to tiagocrosado from comment #2) > Created attachment 324393 [details] [review] > Simple manpage for gnome-boxes Is this a patch? Is it possible that you marked the attachment as patch while it's not a patch? I'm asking cause bugzilla doesn't seem to be able to open it.
I'd advise to use either `git format-patch` for patch file creation or `git-bz attach` to directly upload patch from commit. You'll first need to commit your changes locally. Here are the guidelines for good commit logs: https://wiki.gnome.org/Git/CommitMessages
Comment on attachment 324393 [details] Simple manpage for gnome-boxes (fixed) From f5bc5fecd6ba8cfc1b180c99ed293cfeb92a49ea Mon Sep 17 00:00:00 2001 From: Tiago Rosado <tiagocrosado@hotmail.com> Date: Mon, 21 Mar 2016 18:22:12 +0000 Subject: [PATCH] Simple manpage for gnome-boxes --- gnome-boxes.l | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 gnome-boxes.l diff --git a/gnome-boxes.l b/gnome-boxes.l new file mode 100644 index 0000000..a422a0c --- /dev/null +++ b/gnome-boxes.l @@ -0,0 +1,44 @@ +'\" t +.\" Title: gnome-boxes +.\" Author: Tiago Rosado <tiagocrosado@tecnico.ulisboa.pt> +.\" Date: 20/03/2016 +.\" Manual: User Commands +.\" Language: English +.\" +.TH GNOME-BOXES 1 "" "gnome-boxes" "gnome-boxes" +.SH NAME +gnome-boxes \- A virtualization tool built for GNOME +.SH SYNOPSIS +.B gnome-boxes +[OPTION] ... [\fINAME\fR] ... +.SH DESCRIPTION +.B gnome-boxes +is a simple GNOME 3 application to access remote or virtual systems. + +.SH OPTIONS +When only \fINAME\fR is given the box with the name specified starts. + +.B --help + Display this help + +.B --version + Display version number + +.B -f, --full-screen + Open application in full screen + +.B --checks + Check virtualization capabilities of the host system + +.B --open-uuid=\fIUUID\fR + Open a box by its \fIUUID\fR + +.B --search=\fITERM\fR + Search for a box name with the \fITERM\fR + +.SH BUGS +The bug tracker can be reached visiting the website https://bugzilla.gnome.org/buglist.cgi?product=gnome-boxes. Before sending a bug report, please verify that you have the latest version of gnome-boxes. Many bugs (major and minor) are fixed at each release, and if your is out of date, the problem may already have been solved. + +.SH ADDITIONAL INFORMATION +For further information, visit the website +https://wiki.gnome.org/Apps/Boxes. -- 1.9.1
Created attachment 324494 [details] [review] Manpage for gnome-boxes
Review of attachment 324494 [details] [review]: ::: gnome-boxes.l @@ +38,3 @@ + +.SH BUGS +The bug tracker can be reached visiting the website https://bugzilla.gnome.org/buglist.cgi?product=gnome-boxes. Before sending a bug report, please verify that you have the latest version of gnome-boxes. Many bugs (major and minor) are fixed at each release, and if your is out of date, the problem may already have been solved. Is it not possible to break this line into multiple? If it is, please do so, breaking it at 80 chars.
Created attachment 324496 [details] [review] Manpage fixed with a max line lenght of 80 chars
Thanks but you want to merge the changes to the original patch/commit and upload the file created by `git format-patch` as I said in comment#4. Then I can do a review and apply locally to test..
Created attachment 324500 [details] [review] Manpage for gnome-boxes Is this it? Sorry for the trouble, it's my first time trying to fix a bug trough bugzilla.
(In reply to tiagocrosado from comment #10) > Created attachment 324500 [details] [review] [review] > Manpage for gnome-boxes > > Is this it? Sorry for the trouble, it's my first time trying to fix a bug > trough bugzilla. Yeah and no worries, I know you're new to all this. :) Kudos for making sure older patches are marked obsolete as well. I'll review the patch now..
Review of attachment 324500 [details] [review]: * Shortlog could be improved a bit, e.g "Add manpage for gnome-boxes". * A bit of description would be nice too. * You have not provided the build rules so the manpage will not be installed in the right place. Please check sources of other GNOME software the provide manpages (e.g gnome-calculator) for examples on how to do that and also check where in the source directory structure they keep the manpage. AFAIK many projects generate the manpage as part of the build from comments inside the source code so if we could do the same, that would be lovely. ::: gnome-boxes.l @@ +13,3 @@ +[OPTION] ... [\fINAME\fR] ... +.SH DESCRIPTION +.B gnome-boxes gnome-boxes is the unix-name/command, the name is simply Boxes or GNOME Boxes if context is not clear. @@ +39,3 @@ +.SH BUGS +The bug tracker can be reached visiting the website +.br I removed these .br lines and output through man remained the same so I don't think we need them, they only make it look ugly. @@ +40,3 @@ +The bug tracker can be reached visiting the website +.br +https://bugzilla.gnome.org/buglist.cgi?product=gnome-boxes. You want to provide this URL instead: https://bugzilla.gnome.org/enter_bug.cgi?product=gnome-boxes so users can directly reach the place to file bugs at. @@ +44,3 @@ +Before sending a bug report, please verify that you have the latest version of +.br +gnome-boxes. Many bugs (major and minor) are fixed at each release, and if your * There is trailing whitespaces here and on other lines, please remove them. * your -> your copy of Boxes. @@ +49,3 @@ + +.SH ADDITIONAL INFORMATION +For further information, visit the website 'the website' part is pretty redundant here. Everyone knows what a HTTP URL means. @@ +50,3 @@ +.SH ADDITIONAL INFORMATION +For further information, visit the website +.br I wouldn't add this br either. Would be nice to have an empty line between each line of text and URL (same applies to bz URL above) but if that is not possible, just keep it on the same line.
Are you planning to submit a new patch with all the issues addressed? Please keep in mind that getting as much contributions into the project as possible is important to win SoC project (no guarantees of course).
(In reply to Zeeshan Ali (Khattak) from comment #13) > Are you planning to submit a new patch with all the issues addressed? Please > keep in mind that getting as much contributions into the project as possible > is important to win SoC project (no guarantees of course). I'm having some projects and exams for my degree, but i will probably looking into this issue on the weekend. I also tried to make a dynamic manpage based on source file that states the available options and it is working.However i'm having a bit of a trouble to integrate the manpage installation into the makefile. Is there any guides for this integration? I wasn't able to find them. Thank you
(In reply to Tiago Rosado from comment #14) > (In reply to Zeeshan Ali (Khattak) from comment #13) > > Are you planning to submit a new patch with all the issues addressed? Please > > keep in mind that getting as much contributions into the project as possible > > is important to win SoC project (no guarantees of course). > > I'm having some projects and exams for my degree, but i will probably > looking into this issue on the weekend. Ah ok, no worries. > I also tried to make a dynamic > manpage based on source file that states the available options and it is > working. Glad to hear. > However i'm having a bit of a trouble to integrate the manpage > installation into the makefile. Is there any guides for this integration? I > wasn't able to find them. If I knew much about manpages, I would have added it myself long time ago. :) Your best bet is to look at existing (GNOME and GNOME-related) projects for examples. libosinfo (see the tools directory) is one that I can think of.
Created attachment 325292 [details] [review] Fixed manpage installation I think that this now installing . I will still try to integrate the bash script to make the manpage later.
(In reply to Tiago Rosado from comment #16) > Created attachment 325292 [details] [review] [review] > Fixed manpage installation > > I think that this now installing . It should be easy to test. See if you can see the file in the right place after running `make install` and that `man gnome-boxes` brings it up when you don't have the mangpage in the current directory. > I will still try to integrate the bash script to make the manpage later. I'll review once you have done that.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME'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.gnome.org/GNOME/gnome-boxes/issues/3.