manpages for dcm2niix / dcm2niibatch

[ghisvail]

Both tools are currently missing a corresponding manpage.

[neurolabusc]

A man page would traditionally require files copied to /usr/share/man. In the tradition of the vast majority of tools in our field my software will show you help if you type the command without any parameters (or execute the application with the "-h" parameter):

$ ./dcm2niix
Chris Rorden's dcm2niiX version 25Nov2016 (64-bit MacOS)
usage: dcm2niix [options] <in_folder>
Options :
-b : BIDS sidecar (y/n, default n)
-f : filename (%a=antenna (coil) number, %c=comments, %d=description, %e echo number, %f=folder name, %i ID of patient, %m=manufacturer, %n=name of patient, %p=protocol, %s=series number, %t=time, %u=acquisition number, %z sequence name; default '%p_%e_%4s')
-h : show help
-m : merge 2D slices from same series regardless of study time, echo, coil, orientation, etc. (y/n, default n)
-o : output directory (omit to save to input folder)
-s : single file mode, do not convert other images in folder (y/n, default n)
-t : text notes includes private patient details (y/n, default n)
-v : verbose (y/n, default n)
-x : crop (y/n, default n)
-z : gz compress images (y/i/n, default y) [y=pigz, i=internal, n=no]
Defaults file : /Users/rorden/.dcm2nii.ini
Examples :
dcm2niix /Users/chris/dir
dcm2niix -o /users/cr/outdir/ -z y ~/dicomdir
dcm2niix -f mystudy%s /dicomdir
dcm2niix -o "/dir with spaces/dir" ~/dicomdir

If you wanted to I think you could build this for yourself:

./dcm2niix > dcm2niix.1
sudo cp dcm2niix.1 /usr/local/share/man/man1/
sudo mandb

[ghisvail]

If you wanted to I think you could build this for yourself:

Or use help2man preferably, which would correctly format the help string to a man page. Your solution would likely yield a malformed document.

Besides, manpages are different than help strings. See the output of curl -h vs man curl for an example. You may want to write it in Markdown or reST and let users use pandoc for conversion, instead of using the comparatively less intuitive troff syntax.

[neurolabusc]

I have never used a man page, so I am unfamiliar with the style for these. Why don't you write a document and submit it as a patch to the project. I would be happy to merge your work into the main branch.

[ghisvail]

Why did you close this issue? It should be left opened until the manpages are made available (by yourself or a contributor).

[neurolabusc]

Feel free to submit a patch. I am a single developer who maintains a lot of open source tools. Further, as director for the neuroimaging core of a P50, I have am busy updating other tools (MRIcroGL, NiiStat, nit_preprocess) for other team members. I can think of a laundry list of feature requests for dcm2niix, but I like to keep open issues as known bugs or limitations of the software that I hope to address. For the moment, I think the software has a nice help screen and comprehensive wiki (https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage). Therefore, a man page is not a priority.

[ghisvail]

Feel free to submit a patch.

I am working on it as part of this effort.

I am a single developer who maintains a lot of open source tools.

I know the feeling.

I like to keep open issues as known bugs or limitations of the software that I hope to address.

By systematically closing issues such as this one, you leave no visibility to your community to discuss, help and potentially contribute back. It is also a frustrating experience, as a bug reporter, to have valid issues reported upstream being systematically closed. Issues are not a bad thing, quite the contrary actually.

Therefore, a man page is not a priority.

Then, please leave the issue open and just say so upfront. There is no shame in tagging an issue as a low-priority and leave it for someone else to fix.

[ghisvail]

As an FYI, I have made dcm2niix available to Debian / Ubuntu community. I intend to prepare a manpage for it in the next iteration of the package. I need some more experience (and time) with the tool before being able to write something more detailed than what the help string currently provides.

[ghisvail]

I could also first port the content of the help string to a manpage friendly format as a start. We will see.

[neurolabusc]

How about this
dcm2niix.1.txt

[ghisvail]

@neurolabusc Regarding dcm2niibatch, do you have any suggestion of what should be put in its manpage?

My first guess was that the man page should probably document the content of the YAML file. However, it seems there is not even a way to output a help string (tried -h and --help) to get more information about it. Could you give me more information on this please?

[neurolabusc]

dcm2niibatch was created by @benjaminirving - I just updated the program to provide the comprehensive instructions from the README.MD file if it is executed without a config file, therefore both "dcm2niibatch" as well as "dcm2batch -h" will generate a help file. Feel free to submit a man for this.

[benjaminirving]

Thanks for letting me know @neurolabusc. Will look into it this week.

[benjaminirving]

@neurolabusc, the dcm2batch -h command looks good. I'm happy to submit a man page for dcm2niibatch.

When I initially put together dcm2niibatch, I just added a few options. Are these the best options to expose to the user in dcm2niibatch? Do you think more or less should be included?

Options:
  isGz:             false
  isFlipY:          false
  isVerbose:        false
  isCreateBIDS:     false
  isOnlySingleFile: false

@ghisvail, for testing purposes, if I'm just building dcm2niix but not installing then where can I find the sphinx built man pages to make sure everything is how it should be?

Thanks,
Ben

[ghisvail]

@benjaminirving, you will find the generated manpage somewhere within ${CMAKE_BINARY_DIR}/docs/man.

If you want to add a manpage for dcm2niibatch, just write it in docs/source/dcm2niibatch.rst following a similar syntax and format as dcm2niix.rst and a corresponding tuple to the man_pages list under docs/source/conf.py.

[benjaminirving]

Thanks @neurolabusc and @ghisvail for the info. Nice to have man pages after running make install.

My only issue with the current documentation build setup is that the documentation author is automatically appended to the man page for dcm2niix and dcm2niibatch e.g:

This incorrectly implies that @ghisvail and I are the authors of the entire software. Can we fix the build to remove the author section or write an alternative author section for dcm2niix and dcm2niibatch?

[ghisvail]

Which is correct. The author field is for the manpage, not the software. Le 29 déc. 2016 8:21 PM, "Benjamin Irving" <[email protected]> a écrit :

…

Thanks @neurolabusc <https://github.com/neurolabusc> and @ghisvail <https://github.com/ghisvail> for the info. Nice to have man pages after running make install. My only issue with the current documentation build setup is that the documentation author is automatically appended to the man page for dcm2niix and dcm2niibatch e.g: [image: screen shot 2016-12-29 at 22 16 13] <https://cloud.githubusercontent.com/assets/1849579/21553961/7306f804-ce14-11e6-9d79-54f3426f0052.png> This incorrectly implies that @ghisvail <https://github.com/ghisvail> and I are the authors of the entire software. Can we fix the build to remove the author section or write an alternative author section for dcm2niix and dcm2niibatch? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#64 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AB36b69L0LXXsZGRBfB1nlQ9PCtRI0Xyks5rNBYsgaJpZM4LBuja> .

[benjaminirving]

ok but other man pages such as for git or pdftex list the software authors and various other contributions under Authors.

[ghisvail]

Other projects may do as they please. If you wrote the manpage, then you are the author and may license your work however you like (usually under compatible terms with the software, but not always).

[benjaminirving]

Sure. I get your point.

My only small concern is that there is ambiguity in the use of the Author Section of this project to imply manpage author when the majority of major projects that I know: git, vim, pdflatex etc use it to for project author -- because the reader will most likely interpret this as the author of the entire project. I'm not too bothered either way. Perhaps @neurolabusc would like to extend this section into a paragraph at a later stage e.g. git example below.

[ghisvail]

because the reader will most likely interpret this as the author of the entire project

This information should be found in the project's LICENSE, AUTHORS, CONTRIBUTORS or THANKS file, to name a few of the usual ones.

Again, all projects do as they please. You will find conflicting advice and examples on this matter.

AFAIC, since dcm2niix does not maintain such manifest of contributors and the nature of their respective contribution, I'd want my authorship to remain visible. Of course, you are free to decide otherwise for your man page.

[benjaminirving]

Of course, I completely agree that your manpage authorship (and mine) should remain visible. I was just wondering if more information should be added as well to the author section e.g. the nice little story above from Linus Torvalds. But this is @neurolabusc 's choice and not mine.

Thanks for getting me into Sphinx for manpages. I didn't know it could be used for that :).

[neurolabusc]

I have updated the Author section to say "This manual was developed and is maintained by ..." this clarifies the role and contribution.