Zandronum Chat on our Discord Server Get the latest version: 3.2
Source Code
My View | View Issues | Change Log | Roadmap | Doomseeker Issue Support Ranking | Rules | My Account
  

View Issue Details [ Jump to Notes ] [ Issue History ] [ Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0003247Doomseeker[All Projects] Bugpublic2017-09-01 17:302022-08-25 10:22
ReporterWubTheCaptain 
Assigned To 
PrioritynormalSeverityfeatureReproducibilityN/A
StatusconfirmedResolutionopen 
Platformx86_64 (really cross-platform)OSDebian GNU/LinuxOS Versionbuster/sid
Product Version1.1 
Target VersionFixed in Version 
Summary0003247: Doomseeker's manual page (mdoc/nroff) is missing or incomplete
DescriptionDoomseeker's binary executable should come with at least an English manual page, either in mdoc format (*BSD) or nroff (GNU/Linux) which can be read offline with man(1) utility. It should have as much information as possible about using and configuring the program as feasible and found useful. Here's some recommendations for sections to include:


  • NAME

  • SYNOPSIS

  • DESCRIPTION

  • OPTIONS

  • FILES

  • EXIT STATUS

  • ENVIRONMENT

  • SEE ALSO

  • HISTORY

  • AUTHORS



Sections may be omitted as needed. Even a very minimal man page may be helpful and may be expanded in the future.

The build system should also install it to the appropriate directory (somewhere under /usr/share/man/).

Lintian tag (warning): binary-without-manpage (severity normal, certainty possible)
Steps To Reproduce
$ man doomseeker
No manual entry for doomseeker
See 'man 7 undocumented' for help when manual pages are not available.
Additional InformationNote: Unix man pages only support text and simple formatting. No images, no video (unless you instruct to view or play something already existing on the filesystem).

The program arguments window in graphical interface navigation Help → Program Args may be an useful resource to start from. The online help pages (https://wiki.zandronum.com/Doomseeker) may also be useful.


  • http://mdocml.bsd.lv/

  • http://mdocml.bsd.lv/man/mdoc.7.html

  • http://mdocml.bsd.lv/mdoc/

  • https://www.gnu.org/software/groff/

  • https://liw.fi/manpages/

Attached Filesgz file icon doomseeker-doc-draft1.tar.gz [^] (11,086 bytes) 2017-10-04 06:47

- Relationships
related to 0003248acknowledged Create or convert libwadseeker API documentation to mdoc/nroff manual page format 
related to 0003233closedZalewa Add support for the XDG Base Directory Specification and default to it 
related to 0003282closedZalewa Omitting file from --version-json command line parameter doesn't print to standard output 
parent of 0003290closedWubTheCaptain Doomseeker's --tests option is undocumented 
parent of 0003250closedBlzut3 Doomseeker's --help option is undocumented 
related to 0003295closedZalewa Rename LICENSE files to COPYING 
child of 0003246acknowledged Debian packaging 
child of 0003499assignedPol M Port Doomseeker to OpenBSD 

-  Notes
User avatar (0018226)
Filystea (reporter)
2017-09-03 07:39

 It's gui so I would expect it to have help in the window mod.
But there could be a pointer from man I guess.
User avatar (0018235)
WubTheCaptain (reporter)
2017-09-07 19:36

 I just read from Debian Policy Manual v4.1.0.0 section 12.1: The man pages should be installed in nroff source form.

I personally very much prefer mdoc format over others, but I don't mind doing the conversion by hand if needed.
User avatar (0018418)
WubTheCaptain (reporter)
2017-10-03 05:13
edited on: 2017-10-03 05:16

 I'm working on this today, not finished yet. I have to say, finding documentation for the nroff format is concerningly more difficult to find than mdoc. Oh well, at least I have a lot of examples. (I also discovered a bug or two in Doomseeker while writing the man page.)

Zalewa, Blzut3: Do you have any preference for man page copyright license? LGPLv2.1+, GPLv2+, FDL, something else?
User avatar (0018425)
WubTheCaptain (reporter)
2017-10-04 00:17

 I'm wondering what to do about the undocumented --update-failed command line option.
User avatar (0018428)
Blzut3 (administrator)
2017-10-04 03:28

 I don't have enough knowledge on documentation licensing to have an opinion. If LGPL is an option for documentation then that's probably what I'd go with for uniformity.

As for --update-failed. That would be for internal use only with the auto updater. The most I would document is that it takes one argument. I don't think we have any plans to ensure that the behavior remains consistent between versions.
User avatar (0018429)
WubTheCaptain (reporter)
2017-10-04 06:26
edited on: 2017-10-04 06:27

 I'm currently siding on a free documentation license: GFDL 1.3+. This is negotiable, not set in the stone yet.

The nroff man page source for doomseeker(1) is currently ~ 6.26 KB uncompressed, 245 lines (and 8 pages for a 80x24 terminal when viewed in man).

Some questions to make sure I got things right:


  • If omitted, is the default host:port for --connect and --rcon options always localhost:10666?

  • Should it be mentioned in NOTES section which game engines/plugins have free game data available (e.g. Freedoom)?

  • What exactly is a binary file located at "$HOME/.doomseeker/Zandronum"? It was created on first start-up. Is it relevant to mention in the FILES section? Currently the FILES section lists the IP2C database and three configuration files for Doomseeker.

  • Does Doomseeker 1.1 or 1.2-beta use any environment valuables which should be noted in the ENVIRONMENT section? I'm not aware of any.

  • Is there conformance (CONFORMING TO or STANDARDS section) to any of the various standards listed in standards(7) (or standards listed in mdoc(7) in OpenBSD)? Is there a guideline which C++ standard version Doomseeker source code aims to use (e.g. C++03, C++11, C++14)? I'm thinking of maybe listing FHS and XDG base directory specification here soon.

  • For submitting patches/diffs, where would you prefer manual pages to be located in the project file structure in revision control? I can post the man page and let you decide.

  • Would you be opposed to including an AUTHORS or THANKS file in the project root? My idea is to install this to /usr/share/doc/doomseeker/AUTHORS and reference it from the AUTHORS section in the man page. It would also include my email address, which is not currently included in the copyright notice.
User avatar (0018444)
Blzut3 (administrator)
2017-10-05 01:19
Quote from WubTheCaptain
If omitted, is the default host:port for --connect and --rcon options always localhost:10666?

The port number is defined by the plugin, but yes it will be localhost.
Quote from WubTheCaptain
Should it be mentioned in NOTES section which game engines/plugins have free game data available (e.g. Freedoom)?

Seems out of scope to me. Besides Turok that's all of them.
Quote from WubTheCaptain
What exactly is a binary file located at "$HOME/.doomseeker/Zandronum"? It was created on first start-up. Is it relevant to mention in the FILES section? Currently the FILES section lists the IP2C database and three configuration files for Doomseeker.

This is a dump of the master server response so in the case that it is temporarily offline it can use the last list it got. Although I don't know why I didn't make them standard pcap files.
Quote from WubTheCaptain
Does Doomseeker 1.1 or 1.2-beta use any environment valuables which should be noted in the ENVIRONMENT section? I'm not aware of any.

Besides anything that Qt might be affected by and standard stuff (HOME, etc) no.
Quote from WubTheCaptain
Is there conformance (CONFORMING TO or STANDARDS section) to any of the various standards listed in standards(7) (or standards listed in mdoc(7) in OpenBSD)? Is there a guideline which C++ standard version Doomseeker source code aims to use (e.g. C++03, C++11, C++14)? I'm thinking of maybe listing FHS and XDG base directory specification here soon.

Doomseeker is currently written in C++03.
Quote from WubTheCaptain
For submitting patches/diffs, where would you prefer manual pages to be located in the project file structure in revision control? I can post the man page and let you decide.

The docs directory would be the place to put them, although the files currently in there should probably be reorganized a little.
Quote from WubTheCaptain
Would you be opposed to including an AUTHORS or THANKS file in the project root? My idea is to install this to /usr/share/doc/doomseeker/AUTHORS and reference it from the AUTHORS section in the man page. It would also include my email address, which is not currently included in the copyright notice.

An AUTHORS file is fine. Was thinking that might be useful while I was going commit by commit to find any relevant contributions for the LGPL relicense.
User avatar (0018453)
WubTheCaptain (reporter)
2017-10-07 05:16

 There is no cached master server response file for SRB2 that I can find. Is this a bug, or should I omit the FILES section from doomseeker-srb2(7) man page?
User avatar (0018455)
WubTheCaptain (reporter)
2017-10-07 08:59

 Progress report: doomseeker(1), doomseeker-chocolate(7), doomseeker-odamex(7), doomseeker-srb2(7), doomseeker-turok2ex(7) and doomseeker-zandronum(7) pages are mostly complete and release ready. Related issues may require changes to the documentation, so I'm keeping an eye on them.

The SRB2 question is still valid. I'll attempt post a patch/diff once that's out of the way.

The only missing page now is wadseeker(3), which issue 0003248 is for.
User avatar (0018538)
Blzut3 (administrator)
2017-10-12 00:39

 The lack of a cache would be a bug. SRB2 uses TCP for its master server so it's not able to take advantage of Doomseeker's transparent caching.

Issue Community Support
Only registered users can voice their support. Click here to register, or here to log in.
Supporters: No one explicitly supports this issue yet.
Opponents: No one explicitly opposes this issue yet.

- Issue History
Date Modified Username Field Change
2017-09-01 17:30 WubTheCaptain New Issue
2017-09-01 19:12 Zalewa Relationship added child of 0003246
2017-09-03 07:39 Filystea Note Added: 0018226
2017-09-07 19:36 WubTheCaptain Note Added: 0018235
2017-10-03 05:13 WubTheCaptain Note Added: 0018418
2017-10-03 05:14 WubTheCaptain Summary Doomseeker's manual page (mdoc/groff) is missing or incomplete => Doomseeker's manual page (mdoc/nroff) is missing or incomplete
2017-10-03 05:14 WubTheCaptain Description Updated View Revisions
2017-10-03 05:15 WubTheCaptain Status new => feedback
2017-10-03 05:16 WubTheCaptain Note Edited: 0018418 View Revisions
2017-10-04 00:17 WubTheCaptain Note Added: 0018425
2017-10-04 00:17 WubTheCaptain Status feedback => new
2017-10-04 00:18 WubTheCaptain Status new => feedback
2017-10-04 03:28 Blzut3 Note Added: 0018428
2017-10-04 06:26 WubTheCaptain Note Added: 0018429
2017-10-04 06:26 WubTheCaptain Status feedback => new
2017-10-04 06:26 WubTheCaptain Status new => feedback
2017-10-04 06:26 WubTheCaptain Note Edited: 0018429 View Revisions
2017-10-04 06:27 WubTheCaptain Note Edited: 0018429 View Revisions
2017-10-04 06:47 WubTheCaptain File Added: doomseeker-doc-draft1.tar.gz
2017-10-04 06:48 WubTheCaptain Status feedback => needs review
2017-10-05 01:19 Blzut3 Note Added: 0018444
2017-10-05 01:22 WubTheCaptain Status needs review => acknowledged
2017-10-05 01:55 WubTheCaptain Status acknowledged => confirmed
2017-10-05 02:00 WubTheCaptain Assigned To => WubTheCaptain
2017-10-05 02:00 WubTheCaptain Status confirmed => assigned
2017-10-05 02:56 WubTheCaptain Target Version => 1.2
2017-10-07 05:16 WubTheCaptain Note Added: 0018453
2017-10-07 05:16 WubTheCaptain Status assigned => feedback
2017-10-07 05:31 WubTheCaptain Relationship added related to 0003290
2017-10-07 05:32 WubTheCaptain Relationship added related to 0003250
2017-10-07 05:33 WubTheCaptain Relationship added related to 0003248
2017-10-07 08:55 WubTheCaptain Relationship added related to 0003233
2017-10-07 08:56 WubTheCaptain Relationship added related to 0003282
2017-10-07 08:59 WubTheCaptain Note Added: 0018455
2017-10-07 08:59 WubTheCaptain Status feedback => assigned
2017-10-07 09:07 WubTheCaptain Status assigned => feedback
2017-10-07 09:41 WubTheCaptain Relationship added related to 0003295
2017-10-12 00:39 Blzut3 Note Added: 0018538
2017-10-12 05:11 WubTheCaptain Status feedback => assigned
2018-02-19 22:07 WubTheCaptain Status assigned => confirmed
2018-02-19 22:07 WubTheCaptain Relationship replaced child of 0003290
2018-02-19 22:08 WubTheCaptain Relationship replaced parent of 0003290
2018-02-19 22:08 WubTheCaptain Relationship replaced parent of 0003250
2018-02-19 22:50 WubTheCaptain Additional Information Updated View Revisions
2018-09-19 17:34 WubTheCaptain Relationship added child of 0003499
2018-09-22 15:55 WubTheCaptain Target Version 1.2 =>
2018-10-13 16:50 WubTheCaptain Severity minor => feature
2022-08-25 10:22 WubTheCaptain Assigned To WubTheCaptain =>




Questions or other issues? Contact Us.

Links

Copyright © 2000 - 2025 MantisBT Team
Powered by Mantis Bugtracker