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

 
 

bug #54523: doc: link unmkpp with mkpp

Submitted by:  Juan Pablo Carbajal <juanpi>
Submitted on:  Thu 16 Aug 2018 09:47:38 AM UTC  
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  Juan Pablo Carbajal <juanpi>
Originator Name:  juanpi Open/Closed:  Closed
Release:  dev Operating 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)

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>
Project 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>
Project 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>
Project Administrator
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>
Project MemberIn charge of this item.
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>
Project Administrator
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>
Project MemberIn charge of this item.
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>
Project Administrator
Thu 13 Sep 2018 12:04:31 AM UTC, comment #8: 

ok, pushed changes in changesets 778a0400586b and 6e41caf35af7

Juan Pablo Carbajal <juanpi>
Project MemberIn charge of this item.
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>
Project 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>
Project MemberIn charge of this item.
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>
Project MemberIn charge of this item.
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>
Project 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>
Project 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>
Project MemberIn charge of this item.
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>
Project Administrator
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>
Project MemberIn charge of this item.

 

(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)
  •  

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

    Only project 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.5