Wed 28 Aug 2013 06:18:53 PM UTC, comment #8:
Cruft be gone.
|
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?
|
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)
|
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|