bugGNU Octave - Bugs: bug #48996, comment preceeding texinfo

 
 

bug #48996: comment preceeding texinfo

Submitted by:  Ernst Reissner <ernstreissner>
Submitted on:  Sat 03 Sep 2016 11:01:21 PM UTC  
 
Category: NoneSeverity: 3 - Normal
Priority: 5 - NormalItem Group: None
Status: Wont FixAssigned 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 07 Sep 2016 08:21:35 AM UTC, comment #6:

Thank you Carne.
Now I can see, that also Created: works but
seemingly not at the beginning of the file.

For compiler created sources it would be fine if it were possible
to put the key 'Created' at the beginning of the file
not influencing the docstring.

This would be the requirement.

Ernst Reissner <ernstreissner>
Tue 06 Sep 2016 10:49:42 PM UTC, comment #5:

Doesn't have to be copyright. It will also ignore comment blocks that start with "Author:".

Carnë Draug <carandraug>
Project Member
Tue 06 Sep 2016 10:42:06 PM UTC, comment #4:

My mistake: I thought, that helptext is always texinfo.
If this is not the case, you are right: Copyright is a reasonable marker for sections not going into the functions userdocs.

For my generated matlab sources I just added
'Copyright: none because this file is generated...'

Ernst Reissner <ernstreissner>
Tue 06 Sep 2016 04:42:22 PM UTC, comment #3:

Function doc strings do not have to be texinfo. The separation of the file comment blocks into which is Copyright header and which is doc string is done in the lexer. Only later when the help text is requested does Octave look for the texinfo header.

So a comment block must start with the word Copyright or Author to be recognized as a copyright comment. Otherwise, it is a doc string. The doc string may be plain text, texinfo, html, or maybe other formats in the future.

If the doc string may be plain text, how would you separate header text that is not a doc string from text that is the doc string?

Mike Miller <mtmiller>
Project Administrator
Sun 04 Sep 2016 10:00:58 PM UTC, comment #2:

Ok, it is according to the documentation.
Insofar, it is no bug.

On the other hand, I ask myself,
whether the rule shouldnt be:
all after %% -- texinfo --

This would allow arbitrary information
which is by its nature so that the file should start with.

The copyright notice is just one example,
for generated files, the note that it was generated
is much more useful instead.

What do you think of that?

Ernst Reissner <ernstreissner>
Sun 04 Sep 2016 11:58:43 AM UTC, comment #1:

This might not be a bug, since in the GNU Octave document
"Appendix C Tips and Standards"
"C.3 Conventional Headers for Octave Functions"
it says that
"Octave uses the first block of comments in a function file that do not appear to be a copyright notice as the help text for the file. For Octave to recognize the first comment block as a copyright notice, it must start with the word ‘Copyright’ after stripping the leading comment characters."

Anonymous
Sat 03 Sep 2016 11:01:21 PM UTC, original submission:

It seems as if comments preceeding texinfo
is displayed also in the help text, if not starting with
'Copyright'.

I found that because I generate octave code
which has a leading message sth like
'this matlab file is created by...'.

Ernst Reissner <ernstreissner>

 

(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 ernstreissner (Submitted the item)
  • -unavailable- added by ernstreissner
  •  

    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 3 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Tue 06 Sep 2016 10:43:42 PM UTCmtmillerStatusNone=>Wont Fix
      Open/ClosedOpen=>Closed
    Sat 03 Sep 2016 11:01:21 PM UTCernstreissnerCarbon-Copy-=>Added -unavailable-

    Back to the top


    Powered by Savane 3.1-cleanup1