bugGNU Octave - Bugs: bug #39871, "see also" formatting...

 
 

bug #39871: "see also" formatting for debug.m and in general

Submitted by:  Dan Sebald <sebald>
Submitted on:  Mon 26 Aug 2013 08:11:44 PM UTC  
 
Category: DocumentationSeverity: 3 - Normal
Priority: 5 - NormalItem Group: None
Status: FixedAssigned to: None
Originator Name: Open/Closed: Closed
Release: devOperating System: Any

Add a New Comment(Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

(Jump to the original submission Jump to the original submission)

Wed 28 Aug 2013 06:18:53 PM UTC, comment #8:

Cruft be gone.

Dan Sebald <sebald>
Wed 28 Aug 2013 06:12:59 PM UTC, comment #7:

I was going to check how the "debug" seealso string is formatted in HTML via the GUI's "doc" command, but "debug" doesn't show up in the function list. All the other "seealso" strings when grepping appear to not use carriage returns. Any long list going past eighty characters is simply allowed to extend past eighty characters. Hence, that is why this debug seealso string is different. Remove the spaces in debug, or better yet don't use a carriage return inside the "seealso" argument. Does that seem acceptable?

Dan Sebald <sebald>
Wed 28 Aug 2013 06:08:01 PM UTC, comment #6:

The fseealso code was made useless by a previous jwe changeset, but he missed removing that code. I had noticed that redundancy when digging into this issue and have already removed it in this changeset (http://hg.savannah.gnu.org/hgweb/octave/rev/687872d279be).

I just used some perl code to look through the m-files and debug.m is the only example I find of this so I just took out the spaces (http://hg.savannah.gnu.org/hgweb/octave/rev/f4772605aec3)

Rik <rik5>
Project Administrator
Wed 28 Aug 2013 05:52:05 PM UTC, comment #5:

I put strtrim() around the atoms of the default _makeinfo_.m routine:

and nothing changed. I'm guessing that this routine is not being used. (I don't follow the "end-1" part of it either, seeing as there is no line of code that prints the last element "end".) There are too many "seealso"s in the code when I grep to sort through this.

Is _makeinfo_ where the problem lies? I'm wondering if _makeinfo_ is simply a secondary stage that creates a layout suitable for TeX or HTML and it is some prior stage where the spaces could be removed. I can't think of a reason to leave whitespace intact, although there might be one. No qualms with just changing debug.m either.

Dan Sebald <sebald>
Wed 28 Aug 2013 05:51:27 PM UTC, comment #4:

Absolutely, sorry about the noise. I found those other examples but neglected to see how they were actually formatted in the m-file.

Mike Miller <mtmiller>
Project Administrator
Wed 28 Aug 2013 05:42:55 PM UTC, comment #3:

'polyderiv' and 'isstrprop' both render correctly in plain text because there is no group of spaces after the comment characters which begin the line "## ". This is how debug.m should be fixed and any other instances.

We don't want to use a solution based on a fixed column width because the user may change the size of their window. Makeinfo takes this into account and will wrap where it can. However, at the moment it thinks the atoms that it is dealing with are "dbcont", "dbquit", " dbstack", "dbup", etc. If we remove the spaces the atoms will be correct.

Rendering is not an issue for HTML or TeX (pdf) because these systems ignore the number of spaces and calculate a width on their own. It's only plaintext, when you type 'help XXX', where this is going to be a problem.

Rik <rik5>
Project Administrator
Wed 28 Aug 2013 05:25:02 PM UTC, comment #2:

Or keep the leading space but reduce the right margin by a couple of columns. I'm not sure what the critical column is, but compare with the help for "isstrprop" and "polyderiv". These format correctly for me, and the leading space is correctly removed in the PDF and HTML manuals.

Whichever way this is fixed, please make all three of these docstrings consistent.

Mike Miller <mtmiller>
Project Administrator
Wed 28 Aug 2013 05:15:02 PM UTC, comment #1:

I think this would be simplest to tackle by removing the extra space in debug.m. 'makeinfo' is the one that is expanding the @seealso macro and preserving the spaces and I don't want to try and deal with that.

Rik <rik5>
Project Administrator
Mon 26 Aug 2013 08:11:44 PM UTC, original submission:

The "see also" portion of debug.m turns out as follows:

with big whitespace in the records probably because of the definition:

The question is whether the white space should simply be removed from debug.m, or whether there is a bug in the formatting portion of the documentation no removing whitespace since after all the format code is supposed to figure out where line breaks belong.

Dan Sebald <sebald>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach File(s):
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by mtmiller (Posted a comment)
  • -unavailable- added by rik5 (Posted a comment)
  • -unavailable- added by sebald (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follow 2 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Wed 28 Aug 2013 06:08:01 PM UTCrik5StatusNone=>Fixed
      Open/ClosedOpen=>Closed

    Back to the top


    Powered by Savane 3.1-cleanup1