Mark comments as manuscript notes

[vkbo]

Ref discussion in #801

The comment feature can be used for many thing, and users clearly use them differently. It may be useful to be able to distinguish types of comments more clearly. There is already the option to tag a comment as a synopsis comment. It may be useful to also tag some as a note that can include information about special typesetting, places for illustrations, captions, etc. These could be turned on and off as separate types in the manuscript build.

The syntax should be on the same form as the synopsis:

% Note: This is a note.

[snden]

I don't know what the export will look like in the next version, but I have an idea.
If you are going to distinguish between metadata individually, I think it would be useful to be able to choose whether each of them will be printed or not independently of the others. This could be done with a three-state switch or three radiobuttons with functions:

• all metadata off - print only selected metadata - print all metadata -
  And there would be a place for the user to fill in the selected metadata.
  For example:

If the text contains:

Lorem ipsum
% synopsis: Description of the scene
% note to typesetter: this section capitalized
% illustration: img001.jpg
% Illustration caption: Image 1 - Sunflower
% Note: This is my note
dolor sit amet

and I will need in the result:

Lorem ipsum
this section capitalized
img001.jpg
Image 1 - Sunflower
dolor sit amet

i choose

• print only selected metadata -
  and I fill in the list

note to typesetters
illustration
Illustration caption

The user could thus enter any number type of notes as desired, and then freely choose whether to include the given type in the resulting text or not.

What do you mean?

[vkbo]

I have already considered this, and to be honest I find it a bit over-complicated. Using reStructuredText format as a reference principle, I'd much rather keep a minimal set of pre-defined options:

1. %synopsis: Text The current synopsis feature.
2. %note: Text The proposed editorial note feature.
3. %~ Text The outtakes feature proposed in Add a way to disable text without using the comment feature #1075.
4. % Text For the writer's own comments.

1 and 4 are already there, and can be filtered in the manuscript. 3 would be optional to use in place of regular comments to cross out whole paragraphs. The text could appear in grey with strikethrough. 2 is the one proposed here, which I suggest should be exported with a yellow highlight so that it stands out.

As it is, you can already position illustrations and add captions using the existing @custom reference and comment feature. You are free to use whatever notation you want in comments to make them distinguishable and searchable. Being able to distinguish special notes during build helps to separate the writer's own notes from those relevant to the manuscript, so it has a bunch use cases aside from illustrations, so it is a reasonable feature to add.

[vkbo]

Our discussions gave me an idea to add a How-To section in the documentation on how to use novelWriter for certain things people often ask about. It is also something people can contribute to. #1141,

[vkbo]

Hmm, after giving it some more thought, perhaps it could be possible to tag a note with a category instead of making a lot of different comment formats. For instance:

% Note: [Consistency] The note text.

I'm using this syntax myself in my own writing just to let myself know what stuff is for.

The user can put whatever they want in the square brackets. It could be rendered as a header for the note itself. The index could log them, perhaps cleaning them up to allow for variations like upper/lower case and white spaces. With the way I plan to lay out filter options in the new Build Tool, it should be simple enough to add a generated list of filters for these.

For reference, I plan to add all the filters as a tree with checkboxes an collapsible nodes in the new tool. Then it isn't really an issue that there can be a large number of options. You as a user can just expand the ones you want to take into account.

[snden]

Good idea. I'm currently writing a book where I also use quotes from other books and I'm wondering how to solve this. I don't have many citations there, so I write their sources by hand on a separate page. Maybe it would be possible use
% Note: [Citation]
also to summarize all citations to a particular page.
This feature and option looks like it will be a powerful and useful tool.

[vkbo]

It will be a while until this is implemented, but you could use that syntax already now and it will start working in 2.1. You'd have to export all comments to see it in the manuscript though until the new feature is fully added.

The parser is flexible on the syntax, so %note: and % note: should also work. The keyword is not case sensitive either. I will use the same parsing logic as for synopsis comments.

[vkbo]

Based on discussion #1769 and feature request #1784, we've pretty much concluded that the syntax will be:

%Note: Some note
%Note.Consistency: Another note where "Consistency" is a free form term the user can freely define.

The notes will be collected by a new section of the project index and made available to build output and outline.