[GRASS-dev] [GRASS GIS] #2794: Manual: Overly long description lines

GDAL · November 8, 2015, 5:33pm

#2794: Manual: Overly long description lines
---------------------+---------------------------------
Reporter: neteler | Owner: grass-dev@…
Type: defect | Status: new
Priority: normal | Milestone: 7.0.2
Component: Docs | Version: svn-releasebranch70
Keywords: manual | CPU: Unspecified
Platform: All |
---------------------+---------------------------------
From https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=341643

The top 10 manual pages with too long description line (to be fixed
in main.c or the respective file) are

* d.geodesic
* r3.neighbors
* r.cost
* r.his
* r.neighbors
* r.patch
* r.resamp.rst
* r.series.accumulate
* r.walk
* v.reclass

TODO: Respective one-liner "description"s to be (carefully) shortened.

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/2794>
GRASS GIS <https://grass.osgeo.org>

GDAL · November 8, 2015, 5:36pm

#2794: Manual: Overly long description lines
--------------------------+---------------------------------
  Reporter: neteler | Owner: grass-dev@…
      Type: defect | Status: new
  Priority: normal | Milestone: 7.0.3
Component: Docs | Version: svn-releasebranch70
Resolution: | Keywords: manual
       CPU: Unspecified | Platform: All
--------------------------+---------------------------------
Changes (by martinl):

* milestone: 7.0.2 => 7.0.3

Comment:

Lets move milestone to 7.0.3

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/2794#comment:1>
GRASS GIS <https://grass.osgeo.org>

GDAL · November 8, 2015, 7:30pm

#2794: Manual: Overly long description lines
--------------------------+---------------------------------
  Reporter: neteler | Owner: grass-dev@…
      Type: defect | Status: new
  Priority: normal | Milestone: 7.0.3
Component: Docs | Version: svn-releasebranch70
Resolution: | Keywords: manual
       CPU: Unspecified | Platform: All
--------------------------+---------------------------------

Comment (by wenzeslaus):

I agree, some of them are really long. We have description and when it is
long we add also label which is supposed to be shorter. However, I have no
idea to what it translates in `apropos`. I guess my question is if we need
to shorten the description or put there a label.

When we are at it might be useful to thing about the preferred grammar.
Should it be

{{{
cat (1) - concatenate files and print on the standard output
}}}

which is what `cat` has there or

{{{
cat (1) - Concatenates files and print on the standard
output.
}}}

which is what most GRASS modules are using. This relates also to the
suggestion for short labels I for menu which should use the imperative and
be just 2-3 long as I [https://lists.osgeo.org/pipermail/grass-
dev/2015-October/077134.html recently mentioned].

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/2794#comment:2>
GRASS GIS <https://grass.osgeo.org>

GDAL · April 27, 2019, 9:21pm

#2794: Manual: Overly long description lines
--------------------------+---------------------------------
  Reporter: neteler | Owner: grass-dev@…
      Type: defect | Status: new
  Priority: normal | Milestone: 7.0.7
Component: Docs | Version: svn-releasebranch70
Resolution: | Keywords: manual
       CPU: Unspecified | Platform: All
--------------------------+---------------------------------

Comment (by martinl):

Still relevant?

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/2794#comment:8>
GRASS GIS <https://grass.osgeo.org>

GDAL · April 28, 2019, 3:45pm

#2794: Manual: Overly long description lines
--------------------------+---------------------------------
  Reporter: neteler | Owner: grass-dev@…
      Type: defect | Status: new
  Priority: normal | Milestone: 7.0.7
Component: Docs | Version: svn-releasebranch70
Resolution: | Keywords: manual
       CPU: Unspecified | Platform: All
--------------------------+---------------------------------

Comment (by neteler):

I guess so. Can a (Debian) GRASS GIS trunk user please run (as per
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=341643#15):

{{{
apropos -s 1grass .|perl -nlwe 'print length'|sort -rn|uniq -c|head -50
}}}

?

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/2794#comment:9>
GRASS GIS <https://grass.osgeo.org>

GDAL · April 28, 2019, 4:00pm

#2794: Manual: Overly long description lines
--------------------------+---------------------------------
  Reporter: neteler | Owner: grass-dev@…
      Type: defect | Status: new
  Priority: normal | Milestone: 7.0.7
Component: Docs | Version: svn-releasebranch70
Resolution: | Keywords: manual
       CPU: Unspecified | Platform: All
--------------------------+---------------------------------
Changes (by vincent):

* Attachment "output.txt" added.

apropos output

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/2794>
GRASS GIS <https://grass.osgeo.org>

GDAL · April 28, 2019, 7:17pm

#2794: Manual: Overly long description lines
--------------------------+---------------------------------
  Reporter: neteler | Owner: grass-dev@…
      Type: defect | Status: closed
  Priority: normal | Milestone: 7.2.0
Component: Docs | Version: svn-releasebranch70
Resolution: fixed | Keywords: manual
       CPU: Unspecified | Platform: All
--------------------------+---------------------------------
Changes (by neteler):

* status: new => closed
* resolution: => fixed
* milestone: 7.0.7 => 7.2.0

Comment:

Thanks.

The report looks good to me with respect to the originally, meanwhile
archived Debian bug report.

Closing.

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/2794#comment:10>
GRASS GIS <https://grass.osgeo.org>