View Issue Details

IDProjectCategoryView StatusLast Update
0002781Slicer4Core: Documentation and Wikipublic2018-05-30 01:25
Reporterhjmjohnson Assigned Tojcfr  
PrioritynormalSeverityminorReproducibilityalways
Status acknowledgedResolutionopen 
Product VersionSlicer 4.2.0 
Target VersionbacklogFixed in Version 
Summary0002781: Allow Improved presentation of SEM documentation in SlicerGUI
Description

IF this is a 15 minutes change, it would be great to have. OTHERWISE, it is low prirority and should be pushed off to later.

This is a low priority favor that I have to ask, but it would help with documentation clarity and presentation in the SlicerGUI. I think it may be only 5 minutes to change this, but I don't know what to change in SEM to accomplish this.

I would like to use ![CDATA[ ]]> in my descriptions and acknowledgements

Steps To Reproduce

NOTE: Modify any .xml file and provide formatted description that spans multiple lines with a CDATA encapsulation.

diff --git a/BRAINSFit/BRAINSFit.xml b/BRAINSFit/BRAINSFit.xml
index c8a012b..d7a035e 100644
--- a/BRAINSFit/BRAINSFit.xml
+++ b/BRAINSFit/BRAINSFit.xml
@@ -2,11 +2,26 @@
 <executable>
-  <description>Register a three-dimensional volume to a reference volume (Mattes Mutual Information by default). Full documentation avalable here: http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/BRAINSFit. Method described in BRAINSFit: Mutual Informati

+  <description><![CDATA[
+Register a three-dimensional volume to a reference volume (Mattes Mutual 
+Information by default). Full documentation avalable here: 
+http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/BRAINSFit.
+
+Method described in BRAINSFit: Mutual Information Registrations of Whole-Brain
+3D Images, Using the Insight Toolkit, Johnson H.J., Harris G.,
+Williams K., The Insight Journal, 2007. http://hdl.handle.net/1926/1291
+]]></description>

=============================================
The problem is that the code generation is missing "\" characters at the end of lines 837-843.

 837 fullDescription += "Register a three-dimensional volume to a reference volume (Mattes Mutual 
 838 Information by default). Full documentation avalable here: 
 839 http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/BRAINSFit.
 840 
 841 Method described in BRAINSFit: Mutual Information Registrations of Whole-Brain
 842 3D Images, Using the Insight Toolkit, Johnson H.J., Harris G.,
 843 Williams K., The Insight Journal, 2007. http://hdl.handle.net/1926/1291"; 
Additional Information

This will also help documentation in the automatic nipype wrapping as well.

Hans

TagsNo tags attached.

Activities

jcfr

jcfr

2012-11-21 10:11

administrator   ~0007342

Target attempt 4.2.2

sankhesh

sankhesh

2012-12-05 15:40

developer   ~0007418

Last edited: 2012-12-05 15:41

The issue was thus:
The text is printed as a QString on the "Help and Acknowledgements" pane in the SlicerGUI. QString does not respect new-line("\n") characters. It requires line-breaks ("\<br>"). Pushed a fix on the SlicerExecutionModel repo.
Pushed topic: https://github.com/sankhesh/Slicer/tree/2781-improved-documentation

https://github.com/sankhesh/SlicerExecutionModel/tree/9-respect-multi-line-strings

jcfr

jcfr

2012-12-07 04:13

administrator   ~0007443

Looks good to me. Could you post a screenshot of Slicer UI + example of output of obtained using "--xml" ?

hjmjohnson

hjmjohnson

2012-12-07 05:05

developer   ~0007446

Could you also post the xml file itself? I'd like to modify my XML files and I want to make sure that it matches the format you used.

This will be very nice.

Hans

sankhesh

sankhesh

2012-12-07 06:29

developer   ~0007448

Last edited: 2012-12-07 06:31

I modified the MedianImageFilter.xml file.

diff --git a/Modules/CLI/MedianImageFilter/MedianImageFilter.xml b/Modules/CLI/MedianImageFilter/MedianImageFilter.xml
index 4ee8773..210470c 100644
--- a/Modules/CLI/MedianImageFilter/MedianImageFilter.xml
+++ b/Modules/CLI/MedianImageFilter/MedianImageFilter.xml
@@ -3,7 +3,10 @@
<category>Filtering.Denoising</category>
<index>4</index>
<title>Median Image Filter</title>

  • <description><![CDATA[The MedianImageFilter is commonly used as a robust approach for noise reduction. This filter is particularly efficient against "salt-and-pepper" noise. In other words, it is robust to the presence of gray-level out

  • <description><![CDATA[The MedianImageFilter is commonly used as a robust approach for noise reduction.

  • This filter is particularly efficient against "salt-and-pepper" noise. In other words, it is robust to the presence of gray-level outliers.

  • MedianImageFilter computes the value of each output pixel as the statistical median of the neighborhood of values around the corresponding input pixel.]]></description>
    <version>0.1.0.$Revision$(alpha)</version>
    <documentation-url>http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.2/Modules/MedianImageFilter&lt;/documentation-url>
    <license/>

And the output is:

sankhesh@sankhesh-Dell-System-XPS-L702X:~/Projects/Slicer/bld-new-workdir$ ./Slicer-build/lib/Slicer-4.2/cli-modules/MedianImageFilter --help

.......<Truncated>.....
Description: The MedianImageFilter is commonly used as a robust approach
for noise reduction.

This filter is particularly efficient against 'salt-and-pepper' noise.
In other words, it is robust to the presence of gray-level outliers.

MedianImageFilter computes the value of each output pixel as the
statistical median of the neighborhood of values around the
corresponding input pixel.

================================================================================
./Slicer-build/lib/Slicer-4.2/cli-modules/MedianImageFilter --xml

.......<Truncated>.....

<description><![CDATA[The MedianImageFilter is commonly used as a robust approach for noise reduction.
This filter is particularly efficient against "salt-and-pepper" noise. In other words, it is robust to the presence of gray-level outliers.

MedianImageFilter computes the value of each output pixel as the statistical median of the neighborhood of values around the corresponding input pixel.]]>&lt;/description>

================================================================================

I've attached a screenshot of the GUI as well.

@JC, kindly review and merge the branch https://github.com/sankhesh/SlicerExecutionModel/tree/9-respect-multi-line-strings
so that I can change the commit tag for the SlicerExecutionModel superbuild and push the changes.

2012-12-07 06:29

 

jcfr

jcfr

2012-12-07 06:42

administrator   ~0007449

Seems "--help" output one extra new line when one is expected.

Since the description is:

<![CDATA[The MedianImageFilter is commonly used as a robust approach for noise reduction.
This filter is particularly efficient against "salt-and-pepper" noise. In other words, it is robust to the presence of gray-level outliers.

MedianImageFilter computes the value of each output pixel as the statistical median of the neighborhood of values around the corresponding input pixel.]]>

One would expect:

// -------------
Description: The MedianImageFilter is commonly used as a robust approach
for noise reduction.
This filter is particularly efficient against 'salt-and-pepper' noise.
In other words, it is robust to the presence of gray-level outliers.

MedianImageFilter computes the value of each output pixel as the
statistical median of the neighborhood of values around the
corresponding input pixel.
// -------------

instead of:

// -------------
Description: The MedianImageFilter is commonly used as a robust approach
for noise reduction.

This filter is particularly efficient against 'salt-and-pepper' noise.
In other words, it is robust to the presence of gray-level outliers.

MedianImageFilter computes the value of each output pixel as the
statistical median of the neighborhood of values around the
corresponding input pixel.
// -------------

Let me know what you think.

sankhesh

sankhesh

2012-12-07 07:10

developer   ~0007452

Yes, I saw that. But as you can see that the generated CLP file has the correct number of new-line characters. As a result, when I replace the new-line characters to line-breaks ( https://github.com/sankhesh/Slicer/commit/7c4cf35499f870491e9a42ba53d2cd8a2b91d3e3#L0R173 ), the GUI shows the text correctly.

The issue is in the parser that creates the help text for the commandline. Do you know where that happens?

jcfr

jcfr

2012-12-07 08:34

administrator   ~0007453

Probably something related to tclap. See https://github.com/Slicer/SlicerExecutionModel/tree/master/tclap/include/tclap

sankhesh

sankhesh

2012-12-07 10:22

developer   ~0007455

Last edited: 2012-12-07 10:24

The code just jumps over newline characters ( https://github.com/Slicer/SlicerExecutionModel/blob/master/tclap/include/tclap/StdOutput.h#L256 ) and then prints it with another newline ( https://github.com/Slicer/SlicerExecutionModel/blob/master/tclap/include/tclap/StdOutput.h#L272 )

So, I guess the extra line is by design. Should I change that?

jcfr

jcfr

2012-12-12 16:08

administrator   ~0007498

If there is way to obtain the desired effect without modifying tclap that would be great.

sankhesh

sankhesh

2012-12-17 08:20

developer   ~0007512

Any ideas, Hans? I see that you have written most of StdOutput.h. :-)

jcfr

jcfr

2012-12-17 13:45

administrator   ~0007515

Sankhesh> Hans probably didn't write the tclap library, he simply add the file to the SlicerExecutionModel repo. See http://tclap.git.sourceforge.net/git/gitweb.cgi?p=tclap/tclap;a=summary

If it's something quick, you could simply check if a recent version of tclap has the same problem ...

sankhesh

sankhesh

2012-12-18 05:24

developer   ~0007517

Oops. Sorry Hans.

JC, I checked the latest version of tclap works the same and as I mentioned - the newline is intentional. I will check if I can modify the output after tclap generates it.

hjmjohnson

hjmjohnson

2012-12-18 06:26

developer   ~0007523

It appears that you have done much of the work already, would it be possible to update the internal tclap library? I realize this is a separate issue, but it appears that the tclap library has had 6 years of development since the last syncronization.

In addition, it appears that a few internal patches should be contributed back.

jcfr

jcfr

2012-12-18 08:38

administrator   ~0007528

@Sankhesh: (1) As of today, if I run MedianImageFilter --help. There are no extra line. I wouldn't expect our patch to imply a modification of the underlying library. See also note 7449 (2) Updating the version of tclap would be great, make sure this works reliably on all platforms. (3) Working on these is low priority.

sankhesh

sankhesh

2013-01-14 11:21

developer   ~0007665

@JC, the issue here is that the message is printed using the spaceprint function (https://github.com/sankhesh/SlicerExecutionModel/blob/master/tclap/include/tclap/StdOutput.h#L104) : https://github.com/sankhesh/SlicerExecutionModel/blob/master/tclap/include/tclap/StdOutput.h#L228

This function accepts breaks at newline characters as well as adds line breaks at fixed line lengths. The message is composed of description, contributor and acknowledgements. I can't find a way to isolate the user-added line breaks to the description so as to not print the extra new line.

Secondly, it seems that tclap uses git. Would it make sense to build it as an external project instead of manually adding source code?

jcfr

jcfr

2013-01-29 08:06

administrator   ~0007751

@Sankhesh: Now we have a good understanding of the issue. Could you summarize the change that would be integrated in the different code base ? Thanks

lassoan

lassoan

2018-05-30 01:25

developer   ~0015828

Reteargeting stale issues to backlog.

Issue History

Date Modified Username Field Change
2012-11-21 05:42 hjmjohnson New Issue
2012-11-21 05:42 hjmjohnson Status new => assigned
2012-11-21 05:42 hjmjohnson Assigned To => jcfr
2012-11-21 10:11 jcfr Target Version Slicer 4.3.0 => Slicer 4.2.2
2012-11-21 10:11 jcfr Note Added: 0007342
2012-11-21 11:45 jcfr Assigned To jcfr => sankhesh
2012-12-05 05:38 sankhesh Status assigned => confirmed
2012-12-05 15:40 sankhesh Note Added: 0007418
2012-12-05 15:40 sankhesh Note Edited: 0007418
2012-12-05 15:40 sankhesh Note Edited: 0007418
2012-12-05 15:41 sankhesh Note Edited: 0007418
2012-12-07 04:13 jcfr Note Added: 0007443
2012-12-07 05:05 hjmjohnson Note Added: 0007446
2012-12-07 06:29 sankhesh Note Added: 0007448
2012-12-07 06:29 sankhesh File Added: Screenshot from 2012-12-07 11:18:18.png
2012-12-07 06:31 sankhesh Note Edited: 0007448
2012-12-07 06:42 jcfr Note Added: 0007449
2012-12-07 07:10 sankhesh Note Added: 0007452
2012-12-07 08:34 jcfr Note Added: 0007453
2012-12-07 10:22 sankhesh Note Added: 0007455
2012-12-07 10:24 sankhesh Note Edited: 0007455
2012-12-07 17:59 jcfr Target Version Slicer 4.2.2 => Slicer 4.2.3
2012-12-12 08:18 sankhesh Status confirmed => feedback
2012-12-12 16:08 jcfr Note Added: 0007498
2012-12-17 08:20 sankhesh Note Added: 0007512
2012-12-17 13:45 jcfr Note Added: 0007515
2012-12-18 05:24 sankhesh Note Added: 0007517
2012-12-18 05:59 sankhesh Status feedback => confirmed
2012-12-18 06:26 hjmjohnson Note Added: 0007523
2012-12-18 08:38 jcfr Note Added: 0007528
2013-01-14 11:21 sankhesh Note Added: 0007665
2013-01-29 08:06 jcfr Note Added: 0007751
2013-02-12 09:37 jcfr Target Version Slicer 4.2.3 => Slicer 4.3.0
2013-06-03 05:15 jcfr Status confirmed => assigned
2013-06-03 05:15 jcfr Assigned To sankhesh => jcfr
2013-08-27 12:00 jcfr Target Version Slicer 4.3.0 => Slicer 4.4.0
2014-04-29 10:03 jcfr Status assigned => acknowledged
2014-04-29 10:03 jcfr Target Version Slicer 4.4.0 =>
2016-06-20 14:15 jcfr Category Core: Documentation & Wiki => Core: Documentation and Wiki
2018-03-21 19:11 jcfr Steps to Reproduce Updated View Revisions
2018-05-30 01:25 lassoan Target Version => backlog
2018-05-30 01:25 lassoan Note Added: 0015828