bugGNU Octave - Bugs: bug #54523, doc: link unmkpp with mkpp

 
 

bug #54523: doc: link unmkpp with mkpp

Submitter:  Juan Pablo Carbajal <juanpi>
Submitted:  Thu 16 Aug 2018 09:47:38 AM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  juanpi
Originator Name:  juanpi Open/Closed:  * Closed
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Fri 14 Sep 2018 03:30:55 AM UTC, comment #15: 

And this is still a matter of opinion.  I don't object to one space if the font is a proportional one and the typesetting makes for a larger gap between intra-word spaces and intra-sentence spacing.  But, when using a monospaced font the user is responsible for distinguishing between intra-word and intra-sentence spacing.  I find a monospaced, single-spaced document to be just a forboding wall of text.

Rik <rik5>
Group administrator
Fri 14 Sep 2018 01:01:51 AM UTC, comment #14: 

Just for the record:
1. The standard terminology is:
   "English" spacing means 2 letter spaces after period at
   end of sentence.
   "French" spacing is one letter space. Somewhat surprisingly
   "French" has mainly actually meant "all non-English".
2. The Chicago handbook did switch even though by then
   actual typewriters (monospace) were fading away.
3. End of sentence spacing is fully discussed in Knuth's
   The TeXbook, Chap. 12. TeX and LaTeX still include
   \frenchspacing as a command which invokes "French" spacing.

Wikipedia has a quite good story about all this at:
https://en.wikipedia.org/wiki/History_of_sentence_spacing.

After all that, it seems to be the case that most people  have
gone with the new Chicago rule for plain monospace typewriter
use.

Michael Godfrey <godfrey>
Group Member
Thu 13 Sep 2018 09:56:06 PM UTC, comment #13: 

https://en.wikipedia.org/wiki/Sentence_spacing

Traditional English typewriter convention is to have two spaces after a period. According to that article, the Chicago Manual of Style (popular American English style guide) switched as recently as 2003 to endorsing a single space between sentences. Old habits are hard to break. I type with one space between sentences now, jwe still prefers two spaces :)

Mike Miller <mtmiller>
Group Member
Thu 13 Sep 2018 09:38:42 PM UTC, comment #12: 

Hi Mike,

Thanks. But why the two spaces? Is this parsed in a particular way?

Juan Pablo Carbajal <juanpi>
Group Member
Thu 13 Sep 2018 08:30:44 PM UTC, comment #11: 

That line looks like a paste error in the commit.

I think stylistically Octave has preferred to wrap long lines to fit within 80 columns, as well as flow into the next sentence on the same line when it is less than 80 columns, so that the plain text is readable like a normal paragraph.

I have seen arguments in favor of always breaking a line at the end of a sentence, with the point being that the text processor will merge it into a coherent paragraph for viewing, and the editor has to do less line reformatting when making small changes. But that style has not yet caught on in the Octave documentation. For now consistency is more important. Maybe someday we will go through and add line breaks at the ends of all sentences, but better to do it all at once than incrementally.

Mike Miller <mtmiller>
Group Member
Thu 13 Sep 2018 08:25:47 PM UTC, comment #10: 

Thanks Rik,
What is the meaning of this line?
https://hg.savannah.gnu.org/hgweb/octave/rev/49734a75561f#l1.24

Also I still do not understand why periods followed by two spaces (english?) instead of period and newline.

Juan Pablo Carbajal <juanpi>
Group Member
Thu 13 Sep 2018 06:06:24 PM UTC, comment #9: 

I did a small changeset just to keep the line lengths below 80 characters and wrap text so that @code{} block are not split in half (https://hg.savannah.gnu.org/hgweb/octave/rev/49734a75561f).

Marking as fixed and closing report.

Rik <rik5>
Group administrator
Thu 13 Sep 2018 12:04:31 AM UTC, comment #8: 

ok, pushed changes in changesets 778a0400586b and 6e41caf35af7


Juan Pablo Carbajal <juanpi>
Group Member
Sat 08 Sep 2018 05:44:36 PM UTC, comment #7: 

The error message is about https being required.  Maybe try with 'https://hg.savannah.gnu.org/hgweb/octave/'?

Rik <rik5>
Group administrator
Sat 08 Sep 2018 03:25:54 AM UTC, comment #6: 

Actually I cannot push!
I am using http://hg.savannah.gnu.org/hgweb/octave/ as path, but I get


$ hg push -b stable
pushing to http://hg.savannah.gnu.org/hgweb/octave/
pushing subrepo gnulib to http://hg.octave.org/gnulib
searching for changes
no changes found
searching for changes
abort: HTTP Error 403: ssl required


Juan Pablo Carbajal <juanpi>
Group Member
Sat 08 Sep 2018 12:46:43 AM UTC, comment #5: 

Done! pushed to stable changeset: 6e41caf35af7

I also pushed changeset: 778a0400586ban with improvement for the docstring of mkpp.m

Juan Pablo Carbajal <juanpi>
Group Member
Fri 07 Sep 2018 04:40:27 PM UTC, comment #4: 

Ping!  Juan, go ahead and push your updated changeset.  If it is only documentation it can go on stable.

Rik <rik5>
Group administrator
Tue 28 Aug 2018 12:45:28 AM UTC, comment #3: 

@Juan: Go ahead and push your updated changeset.  Besides, we can always continue to work on it once it is in Mercurial.

Rik <rik5>
Group administrator
Fri 17 Aug 2018 10:36:46 PM UTC, comment #2: 

Hi Mike,

As always your comments are very welcomed!

The code was not mean to be an example. It cold be rendered into one. This needs a change of the text, though. Will work on that.
This way we can get rid of the foor loop, thx!

Shall I push directly to the repository after these changes?

Juan Pablo Carbajal <juanpi>
Group Member
Fri 17 Aug 2018 06:41:30 PM UTC, comment #1: 

I have a few style suggestions for this change. The code example should be written in Octave coding style (spaces around operators, after commas, after function names). It should not be indented from the left, and you are missing a @example block declaration. Something like this


## @example
## @group
## [x, p, n, k, d] = unmkpp (pp)
## pp2  = mkpp (x, p, d)
## fn = fieldnames (pp2);
## for i = 1:numel (fn)
##   assert (pp2.(fn{i}), pp.(fn{i}));
## endfor
## @end group
## @end example


From a readability perspective, I think it would help if you explicitly said in words what the 'assert' is attempting to prove. For someone unfamiliar with these functions (like me), I don't think it's very clear that your example is trying to show "here is how the deconstructed piecewise polynomial structure can be constructed back again into an equivalent structure". Maybe even writing some text and eliminating the distraction of the for loop would be clearer.

The commit message should include both a summary line, with (bug #54523) appended, and a details line with something like


* unmkpp.m: Add example to doc string showing relationship with mkpp.


Mike Miller <mtmiller>
Group Member
Thu 16 Aug 2018 09:47:38 AM UTC, original submission:  

Hi,

Please check that the following documentation improvement follows octave standard. I am a little rusty.

The field X was named "samples" in unmkpp but in all the other pp functions it is called "breaks".

I also added some code that shows how to go back and forth from mkpp to unmkpp.

Thanks

Juan Pablo Carbajal <juanpi>
Group Member

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #44789:  unmkpp_doc.diff added by juanpi (1KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by godfrey (Posted a comment)
  • -email is unavailable- added by mtmiller (Posted a comment)
  • -email is unavailable- added by rik5 (Updated the item)
  • -email is unavailable- added by juanpi (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2018-09-13 rik5 StatusReady For Test Fixed
        Open/ClosedOpen Closed
    2018-09-08 juanpi StatusIn Progress Ready For Test
    2018-08-28 rik5 StatusPatch Submitted In Progress
    2018-08-17 rik5 StatusReady For Test Patch Submitted
    2018-08-16 juanpi Attached File- Added unmkpp_doc.diff, #44789

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code