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

 
 

bug #48996: comment preceeding texinfo

Submitter:  Ernst Reissner <ernstreissner>
Submitted:  Sat 03 Sep 2016 11:01:21 PM UTC
   
 
Category:  None Severity:  3 - Normal
Priority:  5 - Normal Item Group:  None
Status:  Wont Fix Assigned to:  None
Originator Name:  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

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>
Group 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>
Group Member
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 Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by mtmiller (Posted a comment)
  • -email is unavailable- added by ernstreissner (Submitted the item)
  • -email is unavailable- added by ernstreissner
  •  

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

    Date Changed by Updated Field Previous Value => Replaced by
    2016-09-06 mtmiller StatusNone Wont Fix
        Open/ClosedOpen Closed
    2016-09-03 ernstreissner Carbon-Copy- Added -email is unavailable-

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code