Bug 546981 - Menu divider lines in function Outline like Xcode's pragma mark
Summary: Menu divider lines in function Outline like Xcode's pragma mark
Status: RESOLVED FIXED
Alias: None
Product: CDT
Classification: Tools
Component: cdt-editor (show other bugs)
Version: Next   Edit
Hardware: All All
: P3 enhancement with 1 vote (vote)
Target Milestone: 10.4.0   Edit
Assignee: Jonah Graham CLA
QA Contact: Jonah Graham CLA
URL:
Whiteboard:
Keywords: noteworthy
Depends on:
Blocks:
 
Reported: 2019-05-04 15:17 EDT by Greg Willits CLA
Modified: 2021-09-15 10:30 EDT (History)
6 users (show)

See Also:


Attachments
Mockup of Eclipse with Xcode-like pragma mark support (136.67 KB, image/png)
2019-05-04 15:17 EDT, Greg Willits CLA
no flags Details
Mockup of Eclipse with Xcode-like pragma mark support (updated) (156.91 KB, image/png)
2021-05-27 13:56 EDT, Greg Willits CLA
no flags Details
screenshot of prototype of PS3 (63.90 KB, image/png)
2021-06-07 13:42 EDT, Jonah Graham CLA
no flags Details
Eclipse Pragma Mark Color Options Mockup (469.02 KB, image/png)
2021-06-07 16:49 EDT, Greg Willits CLA
no flags Details
Pragma Mark Icon Files (7.31 KB, application/octet-stream)
2021-06-07 17:10 EDT, Greg Willits CLA
no flags Details
drawing error when widest item gets wider (windows only) (5.88 KB, image/png)
2021-06-19 19:20 EDT, Jonah Graham CLA
no flags Details
nested region/endregion as rendered in PS15 (31.97 KB, image/png)
2021-06-21 09:53 EDT, Jonah Graham CLA
no flags Details

Note You need to log in before you can comment on or make changes to this bug.
Description Greg Willits CLA 2019-05-04 15:17:27 EDT
Created attachment 278494 [details]
Mockup of Eclipse with Xcode-like pragma mark support

I've worked with both Eclipse and Xcode for a while.

While I've adapted to many of the differences, one of the simple UI features I really like from Xcode is it's use of #pragma mark to make the layout of the function outline much easier to read and navigate.

I've attached a mockup of what that might look like in Eclipse.

(BTW, I used the web site's UI to navigate to suggest a feature, and it looks like I've ended up in a bug report. Hopefully, this shows up on your end a a feature request.)
Comment 1 Dani Megert CLA 2019-05-05 10:25:10 EDT
For which editor is the "Eclipse Standard Outline"? It's definitely not the standard Java editor outline.
Comment 2 Greg Willits CLA 2019-05-05 15:22:45 EDT
My images are showing C/C++ Editor, but the concept should be applicable (using different syntax) to any language.

I realized I failed to explain what the features are. (Doh!)

Anywhere in the source file outside of a function declaration use pragma mark to indicate a divider, much like a menu divider, to help segregate groups of functions and other declarations when rendered in a function list or file outline.

Use a hyphen to indicate a divider line, and include an optional label. Xcode may support other form, but the three I find most useful are: 

Add a divider and a label and a divider (the Public example in my image).

#pragma mark - Public -

Add a divider and a label (the Accessors example in my image).

#pragma mark - Accessors

Add a plain divider with no label (not shown in my image, looks just like a menu divider)

#pragma mark -
Comment 3 Andrey Loskutov CLA 2019-05-05 15:37:38 EDT
I believe I've seen that we can add @category "name" tags to javadoc and say outline to show that category only (or not). Is this something you are looking for?
Comment 4 Greg Willits CLA 2019-05-05 16:32:12 EDT
Had to research that. As far as I can tell, that feature of @category in the Outline is for filtering--categories are listed in a separate menu, and they're selected to filter what shows up in the outline view much like the Hide/Show Static button, etc. 

That's not what pragma mark does (nor what I'm looking for). It doesn't help identify group membership for each function.

To understand pragma mark, I guess the basic paradigm is to see the outline as a menu. In menus, there are groups of related menu items. Menu dividers (the lines) are used to segregate those groups.

Any file's collection of functions also likely have conceptual groups. What I'm looking to do is have divider lines rendered in the Outline itself to provide visual clarity in the segregation of those groups.

Pragma mark is used to indicate where those lines should go with the ability to also have a label rendered.

Therefore, in code, you might have the following. As each pragma is encountered, a divider line is rendered. (BTW, this would work in the header and implementation files.)


#include <stdlib.h>
// (etc.)


#pragma mark   - Public API -

void my_function(void)
{
}

void my_function(void)
{
}



#pragma mark   - Accessors


void my_function(void)
{
}

void my_function(void)
{
}



#pragma mark   - Private API -

void my_function(void)
{
}

void my_function(void)
{
}


#pragma mark   - Parsing & Interpreting

void my_function(void)
{
}

void my_function(void)
{
}
Comment 5 Dani Megert CLA 2019-05-06 04:20:33 EDT
(In reply to Greg Willits from comment #4)
> Had to research that. As far as I can tell, that feature of @category in the
> Outline is for filtering--categories are listed in a separate menu, and
> they're selected to filter what shows up in the outline view much like the
> Hide/Show Static button, etc. 
Correct.


Maybe start first in the C++ editor and if it gets well received move it to platform?
Comment 6 Greg Willits CLA 2019-05-06 12:00:23 EDT
Will do. I assume I just change the Product field to CDT (which I've done).
Comment 7 Marc-André Laperle CLA 2019-05-20 02:22:49 EDT
That would be neat. If I understand correctly what #pragma mark does, it sounds like we could have something in the outline to cover both cases of "#pragma mark" and also "#pragma region" (MSVC, Clang). It could also be supported in the editor folding.
Comment 8 Greg Willits CLA 2021-05-27 13:56:29 EDT
Created attachment 286465 [details]
Mockup of Eclipse with Xcode-like pragma mark support (updated)

A mockup comparing the existing Eclipse Outline view to an Xcode outline, and the suggested new Eclipse outline which would be much easier to navigate, and provide a much better overview of the file's organization.
Comment 9 Eclipse Genie CLA 2021-06-03 22:05:34 EDT
New Gerrit change created: https://git.eclipse.org/r/c/cdt/org.eclipse.cdt/+/181423
Comment 10 Jonah Graham CLA 2021-06-03 22:43:29 EDT
(In reply to Greg Willits from comment #8)
> Created attachment 286465 [details]
> Mockup of Eclipse with Xcode-like pragma mark support (updated)

Is this mockup purely a "photoshop" job - or have you looked into how to render the horizontal lines or other aspects of the UI we can use as a starting point?
Comment 11 Greg Willits CLA 2021-06-03 23:32:29 EDT
(In reply to Jonah Graham from comment #10)
> Is this mockup purely a "photoshop" job - or...

My image is just a Photoshop job. The only Java I've read is from Fowler's patterns books, and I know nothing about the inner workings of Eclipse.

I'm more than happy to participate however I can (specs, docs, testing, etc.). Don't know how useful I could be for anything code related.
Comment 12 jan baeyens CLA 2021-06-04 08:01:07 EDT
I don't know how or when I would like to use this feature but it looks very attractive to me as I'm an avid user of the outline view.

My architectural mind has some questions though which I think we should think about before getting to deep into the code. 
1) Why do some pragma markers have 2 lines and others 1 in the mockup?
2) do we want these divider lines from the mockup?
3) how are we going to handle sorting?
4) how are we going to handle filtering?
5) Do we want to add a grouping?

My 2 cents on these questions
1) I think it is an error in the mockup
2) I think the divider lines are not a good idea
3) I would just sort like all other elements in the list
4) I would add a icon button to show hide these elements like currently available for statics, non public members ...
5) I would add it to grouping

Unfortunately my UI java coding and my icon creation skills are below my expectations so I will not be able to help with the actual implementation

I can help with internationalisation translating to Dutch :-)

Jantje
Comment 13 Jonah Graham CLA 2021-06-04 09:58:36 EDT
Is "pragma mark" documented/standardized at all?
Comment 14 Jonah Graham CLA 2021-06-04 09:59:54 EDT
Jantje added this link in Gerrit that is relevant https://stackoverflow.com/questions/6853821/what-is-the-significance-of-pragma-marks-why-do-we-need-pragma-marks#6853831
Comment 15 jan baeyens CLA 2021-06-04 11:44:47 EDT
I need to revise my answer to question 1
1) Why do some pragma markers have 2 lines and others 1 in the mockup?

#pragma mark - creates a dividing line. So
#pragma - bla bla - 
should make a entry named "bla bla" between 2 dividing lines
Comment 16 Greg Willits CLA 2021-06-04 12:35:44 EDT
(In reply to jan baeyens from comment #12)
> My architectural mind has some questions though which I think we should
> think about before getting to deep into the code. 

Thanks for these Jan. I don't know the implications to various Eclipse uses well enough, so these questions help.

First let me state the foundational purposes of the pragma marks and divider lines are twofold: 

(A) identify file organization, and 
(B) break up and group the list to make it faster to find a specific function.

I consider these two purposes when thinking about your questions.


> 1) Why do some pragma markers have 2 lines and others 1 in the mockup?

If you look closely at my image, you'll see hyphens before and/or after the label. The hyphens generate divider lines, and are technically optional markup. So, there are actually five legitimate markups:

#pragma mark Label      // no divider lines, but a bold Label inline in the list
#pragma mark - Label    // divider line above the bold Label
#pragma mark - Label -  // divider line above and below the bold Label
#pragma mark Label -    // divider line below the bold Label
#pragma mark -          // divider line and no Label


> 2) do we want these divider lines from the mockup?

IMO, absolutely. They are a key design element which accentuates the file organization and makes the outline faster to navigate. They exist for the same reason as divider lines in menus exist. The main purpose of this request is to get the divider lines in the outline. Without them, the label is just another set of words mashed into the list making it difficult to read through.

> 3) how are we going to handle sorting?

The purpose of sorting the outline is to make it faster to find a specific function. That's an alternative way to view the function list with an overlapping purpose to the pragma solution. So, if the user chooses to sort the outline, there's no value in displaying the pragma labels (or dividers). The labels and dividers would be confusing, and with functions sorted alphabetically, the extra labels would just get in the way.

> 4) how are we going to handle filtering?

You suggest add a filter to show/hide them. Personally, I would never not want them (except for the sort scenario), but maybe others see it your way.

However, because Eclipse does have the filtering, there is a scenario which does need thought about. A pragma mark may be added by a user to identify a group of items which are filtered out. For example, I routinely use in C:

#pragma mark - Private Functions - 
// down here are static functions
// And there could be other pragma dividers labeling groups of static functions

If all static functions are filtered out, the pragma label would still be rendered. Personally, I still find that OK because that fits the purpose (A) in revealing the structure of the file. Even if the static items are hidden, it would not bother me to see the section labels.

However, I can see some people being annoyed by extra labels and lines because for them the purpose of filtering is probably to simplify the list.

Maybe this is where your suggestion of show/hide the pragma labels does become useful.


> 5) Do we want to add a grouping?

This I have no real experience with. I group includes to reduce that noise, but that's it. I write my code to naturally group #defines anyway so the pragma labels would still be in the correct order for me, and "Group Methods" does nothing in C files. I can see if people write their files a certain way that some pragma labels would get out of sync similar to the filtering results.
Comment 17 Greg Willits CLA 2021-06-04 12:47:59 EDT
(In reply to Jonah Graham from comment #13)
> Is "pragma mark" documented/standardized at all?

All the Apple docs links I can find now just give brief mention of it showing Swift instead of Obj-C (different syntax).

There are five 'mark' variants supported in Xcode that I know of:

#pragma mark Label      // no divider lines, but a bold Label inline in the list
#pragma mark - Label    // divider line above the bold Label
#pragma mark - Label -  // divider line above and below the bold Label
#pragma mark Label -    // divider line below the bold Label
#pragma mark -          // divider line and no Label
Comment 18 Greg Willits CLA 2021-06-04 13:02:09 EDT
(In reply to Greg Willits from comment #16)
> (In reply to jan baeyens from comment #12)
> > My architectural mind has some questions though which I think we should
> > think about before getting to deep into the code. 
> 
> > 2) do we want these divider lines from the mockup?
> 
> IMO, absolutely. They are a key design element which accentuates the file
> organization and makes the outline faster to navigate. They exist for the
> same reason as divider lines in menus exist. The main purpose of this
> request is to get the divider lines in the outline. Without them, the label
> is just another set of words mashed into the list making it difficult to
> read through.

OK, my turn to modify my response :-) The lines themselves may not be necessary as long as the dividing spaces are included. So, using ASCII art here, the menu outline be rendered like this:

# MY_CONSTANT
# MY_OTHER_CONSTANT

- My Mark Label

o someFunction1()
o someFunction2()
o someFunction3()

- Another Label
o someFunction4()
o someFunction5()
o someFunction6()

o someFunction7()
o someFunction8()
o someFunction9()


So no lines, but at least big spaces in response to the hyphens in the mark statement. Note I am showing a space between function 6 & 7 with no label in response to #pragma mark -

I can see that working out well too. Since it's not technically a floating menu, fewer lines could make the design cleaner. I can do another graphic mockup of that alternative if you'd like.
Comment 19 Jonah Graham CLA 2021-06-04 13:44:52 EDT
Most of this is pretty straightforward. The thing I don't know how to do is to make either dividing lines or blank lines in the outline view.

Blank lines could just be a tree item that is empty or with only what space in it.

For that aspect someone needs to do a little research on rendering in the tree view.

Is there something in the snippets or an existing Eclipse UI that we can replicate? 
https://www.eclipse.org/swt/snippets
https://wiki.eclipse.org/JFaceSnippets
Comment 20 Jonah Graham CLA 2021-06-04 13:47:38 EDT
https://www.eclipse.org/articles/article.php?file=Article-CustomDrawingTableAndTreeItems/index.html may have useful info too. We could fully custom draw the line.
Comment 21 Greg Willits CLA 2021-06-04 13:55:53 EDT
(In reply to Jonah Graham from comment #19)
> Most of this is pretty straightforward. The thing I don't know how to do is
> to make either dividing lines or blank lines in the outline view.

Could anything from the Tasks view help -- that has lines between each item.

I'll try poking around, but I have a steep learning curve. I am somewhat familiar with the view object classes in Apple's GUI, and customization of them, etc. So, I can look for parallels with the List views to see what options there are, or how to hook into a custom draw routine.

I take it JFace and SWT are the core UI systems?
Comment 22 Greg Willits CLA 2021-06-04 14:37:15 EDT
(In reply to Jonah Graham from comment #19)
> 
> Blank lines could just be a tree item that is empty or with only what space
> in it.
> 
> For that aspect someone needs to do a little research on rendering in the
> tree view.

What I would hope to find is that the tree widget has a delegate for row configuration or custom drawing. The delegate would read the type of row and then either exit with no action or (if pragma mark?) modify whatever is necessary to set the row height.

If there's enough flexibility built into the widget, there should be a way to modify the height of an individual row. It might be necessary to have to draw the whole row (replicating the behavior of the standard code), and in the worst case, the whole widget has to be duplicated to extend the behavior.

That's the info I'm looking for.
Comment 23 Greg Willits CLA 2021-06-04 14:50:37 EDT
(In reply to Greg Willits from comment #22)
> (In reply to Jonah Graham from comment #19)
> > 
> > Blank lines could just be a tree item that is empty or with only what space
> > in it.
> > 
> > For that aspect someone needs to do a little research on rendering in the
> > tree view.
> 
> What I would hope to find is that the tree widget has a delegate for row
> configuration or custom drawing. The delegate would read the type of row and
> then either exit with no action or (if pragma mark?) modify whatever is
> necessary to set the row height.
> 
> If there's enough flexibility built into the widget, there should be a way
> to modify the height of an individual row. It might be necessary to have to
> draw the whole row (replicating the behavior of the standard code), and in
> the worst case, the whole widget has to be duplicated to extend the behavior.
> 
> That's the info I'm looking for.


This conversation seems to be relevant?
https://stackoverflow.com/questions/10003632/change-row-height-in-swt-table-tree
Comment 24 Jonah Graham CLA 2021-06-07 10:37:33 EDT
I checked on twitter for suggestions on how to do the lines - https://twitter.com/JonahGrahamKC/status/1401019386350219265 - Mickael's answer:

I don't think the SWT API allows to draw lines/separators in Trees. It could be an addition  if all target toolkits do support it (eg like `new TreeItem(SWT.SEPARATOR)`.
Otherwise, you'd need to do custom drawing of the tree; or to create a tree item with `---------` as label ;)
Comment 25 Jonah Graham CLA 2021-06-07 13:42:26 EDT
Created attachment 286539 [details]
screenshot of prototype of PS3

I am about to push PS3 which I have prototyped up the dividing lines either side of the mark.
Comment 26 Greg Willits CLA 2021-06-07 14:42:33 EDT
(In reply to Jonah Graham from comment #25)
> Created attachment 286539 [details]
> screenshot of prototype of PS3
> 
> I am about to push PS3 which I have prototyped up the dividing lines either
> side of the mark.

Nice. Humming along!

I know for now just getting infrastructure is the main task, but some notes about the design once the details of that become more forefront:

* The lines should be quite light -- probably the same color as the Outline frame when it is inactive. They should be light like menu separators, and since we don't want them darker than an inactive frame, that inactive frame color looks about right to me for both purposes.

* The labels should be lighter than the outline text as well. Probably something in the territory of RGB #666666 at the darkest to #999999 at the lightest. I'm partial to #808080 (R128, G128, B128) myself.

Thanks for your work on this!
Comment 27 Greg Willits CLA 2021-06-07 14:53:28 EDT
(In reply to Greg Willits from comment #26)
> I know for now just getting infrastructure is the main task, but some notes
> about the design once the details of that become more forefront:

Oh, BTW, my original mockup showed a red dash as an icon in the left column. John, your screenshot did not. I put that there assuming someone might think it is necessary for all rows to have an icon. But IMO, it is not necessary. The mark label doesn't need an icon to help identify what it is, and the list is certainly cleaner w/o the icon for those rows. So I think the way you have the label lined up and w/o an icon is fine.
Comment 28 Jonah Graham CLA 2021-06-07 14:54:45 EDT
Thanks - I transferred the comment 26 to the gerrit review.

@Greg - can you make the image/icon for the Mark element? If so, please attach them here and sign the ECA https://accounts.eclipse.org/user/eca

We need two images - ideally png - a 16x16 normal icon and a 32x32 hidpi icon.
Comment 29 Jonah Graham CLA 2021-06-07 14:55:44 EDT
(In reply to Jonah Graham from comment #28)
> @Greg - can you make the image/icon for the Mark element? If so, please
> attach them here and sign the ECA https://accounts.eclipse.org/user/eca

I read comment 27 after writing this.
Comment 30 Greg Willits CLA 2021-06-07 14:56:26 EDT
(In reply to Jonah Graham from comment #28)
> Thanks - I transferred the comment 26 to the gerrit review.
> 
> @Greg - can you make the image/icon for the Mark element? If so, please
> attach them here and sign the ECA https://accounts.eclipse.org/user/eca
> 
> We need two images - ideally png - a 16x16 normal icon and a 32x32 hidpi
> icon.

Haha. "Two comments passing in the night" -- if they are needed, yes, I will do that.
Comment 31 Jonah Graham CLA 2021-06-07 15:02:46 EDT
(In reply to Greg Willits from comment #30)
> Haha. "Two comments passing in the night" -- if they are needed, yes, I will
> do that.

Brilliant - thanks.
Comment 32 Jonah Graham CLA 2021-06-07 15:09:57 EDT
(In reply to Marc-André Laperle from comment #7)
> That would be neat. If I understand correctly what #pragma mark does, it
> sounds like we could have something in the outline to cover both cases of
> "#pragma mark" and also "#pragma region" (MSVC, Clang). It could also be
> supported in the editor folding.

Within the scope of this bug I am just doing #pragma mark in the outline view. I could do #pragma region in the outline view too. I am not considering code folding in scope of the bug.
Comment 33 Jonah Graham CLA 2021-06-07 15:32:24 EDT
(In reply to Jonah Graham from comment #28)
> We need two images - ideally png - a 16x16 normal icon and a 32x32 hidpi
> icon.

PS These should have transparent backgrounds that work in light and dark mode.
Comment 34 Greg Willits CLA 2021-06-07 16:49:43 EDT
Created attachment 286541 [details]
Eclipse Pragma Mark Color Options Mockup

I've mocked up 6 examples with 3 options for the label color and 2 options for the hyphen icon color.

The Label text colors left to right are #000000, #505050, and #808080.

The top row shows the red icons. The bottom row has the "gray" icons, but each case has the icon the same color as the text.

Hyphen Icon -- The hyphen connection should be obvious. For color, there's two philosophies: it should stand out (red), or  it should be subtle (gray). Either way, it should not be green (IMO). The red color is the same as the S color. There's no connection, it's just that I don't think there should be a new color introduced (more colors == more noise), and that red has good contrast. For the gray options, it looked weird if it was not the same as the text, so whatever the label text is, that should be the icon color as well.

Text Color -- At first I liked the lighter one, but after more experiments, I like the middle 505050. The 000000 is too strong. It demands too much eye attention when trying to scan the function names. The lighter ons is great when there's a line above and below, but it's too light when there's no line or just one line. It's too hard to spot in the function list. After some tests, I think the 505050 one has the right balance. I can ignore it when scanning function names, and I can see it when scanning for labels.
Comment 35 Greg Willits CLA 2021-06-07 17:10:24 EDT
Created attachment 286542 [details]
Pragma Mark Icon Files

I've attached icon files in 16x16 and 32x32 PNG in the four colors of my latest mockup. That way you can play with the color schemes, and choose the final set.
Comment 36 Jonah Graham CLA 2021-06-07 17:13:39 EDT
Cool - I prefer the middle one too on a quick scan.

The same decisions need to be made for the default dark theme too. 

The new colors will be the default, but exposed to user to customize with either CSS or Preferences -> Appearance -> Colors and Fonts -> C/C++ -> Outline

The icons will not be customizable - so they need to work in any (reasonable) theme.

(In reply to Greg Willits from comment #35)
> Created attachment 286542 [details]
> Pragma Mark Icon Files
> 
> I've attached icon files in 16x16 and 32x32 PNG in the four colors of my
> latest mockup. That way you can play with the color schemes, and choose the
> final set.

Great. Please sign the ECA so we can use this work. https://accounts.eclipse.org/user/eca
Comment 37 Greg Willits CLA 2021-06-07 17:15:25 EDT
(In reply to Jonah Graham from comment #36)
> Please sign the ECA so we can use this work.
> https://accounts.eclipse.org/user/eca

I think I just did that unless I skipped a final step?
Comment 38 Jonah Graham CLA 2021-06-07 17:17:02 EDT
(In reply to Greg Willits from comment #37)
> (In reply to Jonah Graham from comment #36)
> > Please sign the ECA so we can use this work.
> > https://accounts.eclipse.org/user/eca
> 
> I think I just did that unless I skipped a final step?

OK. On the checker I get "There is a valid ECA on file for gwillits@marway.com." I assume the red ECA next to your name in Bugzilla will update in due course.
Comment 39 Jonah Graham CLA 2021-06-13 13:20:17 EDT
My latest PS adds the icons and adds color and font preferences as well as #pragma region support.
Comment 40 Eclipse Genie CLA 2021-06-15 22:13:46 EDT
New Gerrit change created: https://git.eclipse.org/r/c/cdt/org.eclipse.cdt/+/182019
Comment 41 Jonah Graham CLA 2021-06-19 19:20:04 EDT
Created attachment 286636 [details]
drawing error when widest item gets wider (windows only)
Comment 42 Jonah Graham CLA 2021-06-20 14:38:17 EDT
@Greg the feature is ready. Can you give it a test? p2 site for the change is https://ci.eclipse.org/cdt/job/cdt-verify-test-cdt-other-pipeline/3555/artifact/releng/org.eclipse.cdt.repo/target/repository/
Comment 43 Greg Willits CLA 2021-06-20 19:35:54 EDT
(In reply to Jonah Graham from comment #42)
> @Greg the feature is ready. Can you give it a test? p2 site for the change
> is
> https://ci.eclipse.org/cdt/job/cdt-verify-test-cdt-other-pipeline/3555/
> artifact/releng/org.eclipse.cdt.repo/target/repository/


@Jonah — Just back from a vacation. Will try soon. Had a peek at the link — afraid I have no idea what to do with those files.
Comment 44 Jonah Graham CLA 2021-06-20 20:11:53 EDT
It is a url you can use in install new software (help menu) , see this screenshot https://download.eclipse.org/errors/content/eclipse-software-install-win10-v1.png
Comment 45 Greg Willits CLA 2021-06-20 22:15:34 EDT
(In reply to Jonah Graham from comment #44)
> It is a url you can use in install new software (help menu)

Ah. My production environment is a 2021-03 I probably shouldn't mess with yet, so I installed a fresh 2021-06 instance, then installed updates with your URL.

First glance, it seems to be working quite well. Will give a deeper test drive tomorrow to see if I can confuse it.

For me, this is awesome to be able to see an overall file map again. A few years ago I wrote a lot of plain C in Xcode (using mark) before migrating the project to a 3rd party embedded IDE based on Eclipse. So, to see those again is instantly making the files more readable and navigation faster.
Comment 46 Jonah Graham CLA 2021-06-21 09:53:48 EDT
Created attachment 286647 [details]
nested region/endregion as rendered in PS15
Comment 47 Greg Willits CLA 2021-06-21 13:09:37 EDT
(In reply to Jonah Graham from comment #42)
> @Greg the feature is ready. Can you give it a test?

So far, I'm not seeing anything I would call a problem.


### Use cases which make the most sense. These are all working fine for me.

I have numerous instances of most of these all over may code already, and they're working fine. Some I played with for testing the feature.

Line (#pragma mark -)

Label (#pragma mark Label)

Line, Label (#pragma mark - Label)

Line, Label, Line (#pragma mark - Label -)

Render only first and last hyphen on any one line as lines; render the others as text in the label
(#pragma mark - ----- Label ----- -)

Use three pragmas instead of one — should look the same (it does).
#pragma mark -
#pragma mark Label
#pragma mark -


### Use cases which don’t make much sense, but let’s see what happens:

Label, Line (#pragma mark Label -) — not practical, but it works as it should.

This works/looks right when includes are not grouped.
But when grouped, the marks are rendered below the nested group.
Personally, I don’t do this, but maybe grouping affects other practical areas? None seem to apply to my C code, but they probably would for C++.

```
#include "mProject.h"

#pragma mark - StdLib
#include <stdlib.h>
#include <stdio.h>
#include <stdarg.h>
#include <limits.h>
#include <errno.h>

#pragma mark - mFramework
#include "mCommonConsts.h"
#include "mString.h"
#include "mLogConstants.h"
#include "mLogRouter.h"
#include "mLogWrite.h"
```

Adding #pragma mark in the middle of a function renders in the outline right after the function listing in the outline. Again, I wouldn’t be using that, but the consequences are logical.
Comment 48 Jonah Graham CLA 2021-06-21 13:30:10 EDT
Excellent - thanks for the feedback. 

> But when grouped, the marks are rendered below the nested group.

The groups extract items from the model and display them as groups - I may be able to identify #pragma marks between different #includes so that the marks appeared in the groups, but I don't know what heuristic to apply, especially when there are multiple types of items.

For now, barring any strong objection, I will leave this use case until I have a concrete use case.

The one thing that I may do is add a toggle for the marks as Jantje suggested:
> 4) I would add a icon button to show hide these elements like currently available for statics, non public members ...
Comment 49 Greg Willits CLA 2021-06-21 14:12:30 EDT
(In reply to Jonah Graham from comment #48)
> Excellent - thanks for the feedback. 
> 
> > But when grouped, the marks are rendered below the nested group.
> 
> The groups extract items from the model and display them as groups - I may
> be able to identify #pragma marks between different #includes so that the
> marks appeared in the groups, but I don't know what heuristic to apply,
> especially when there are multiple types of items.

Yep, I can see several edge cases, especially if someone tends to spread #includes throughout the code, and there's conditional builds a mark could be wrapped in. 

 
> For now, barring any strong objection, I will leave this use case until I
> have a concrete use case.

Agreed. I think this one will be rare enough to not worry about it yet.


> The one thing that I may do is add a toggle for the marks as Jantje
> suggested:
> > 4) I would add a icon button to show hide these elements like currently available for statics, non public members ...

That's a reasonable option/work around for when the grouping/marking gets whacky -- maybe add it to the ... menu so as not to make the existing icon row any bulkier, and to not litter the UI with an option many people may not end up using.
Comment 50 Jonah Graham CLA 2021-06-21 14:26:51 EDT
(In reply to Greg Willits from comment #49)
>[...]-- maybe add it to the ... menu so as not to make the existing icon
> row any bulkier, and to not litter the UI with an option many people may not
> end up using.
+1
Comment 51 Greg Willits CLA 2021-06-21 15:42:41 EDT
@Jonah — So, a question. The programming for the feature gets done, eventually it ships. That process is what it is, and eventually this shows up in a release of CDT.

But... in my case I will mostly be using embedded development tools from companies which have based their customized IDEs on Eclipse. They don't always evolve at the pace of CDT itself. I'm using native CDT now to create a pre-RTOS version of my application, but eventually will be back on 3rd party IDEs.

For now, I'm wondering (more theoretically vs a request) if this can be delivered as a plugin which should work with such 3rd party versions (Siemens/Mentor, STM, etc.)
Comment 52 Jonah Graham CLA 2021-06-21 17:38:54 EDT
(In reply to Greg Willits from comment #51)
> @Jonah — So, a question. The programming for the feature gets done,
> eventually it ships. That process is what it is, and eventually this shows
> up in a release of CDT.

Yup - aiming to have this available in the next milestone build (early July) and have it released along with 2021-09 release in Sept.

> 
> But... in my case I will mostly be using embedded development tools from
> companies which have based their customized IDEs on Eclipse. They don't
> always evolve at the pace of CDT itself. I'm using native CDT now to create
> a pre-RTOS version of my application, but eventually will be back on 3rd
> party IDEs.
> 
> For now, I'm wondering (more theoretically vs a request) if this can be
> delivered as a plugin which should work with such 3rd party versions
> (Siemens/Mentor, STM, etc.)

Short answer is not a chance :-) The current implementation relies on changing lots of internals of CDT to expose #pragmas from the AST up to the UI and then decorating the UI in a new way. Theoretically there may be stuff that could be done as a plugin, but it would be much more work than this solution. 

The best thing to do is put pressure on your silicon or tools vendor to keep up to date with CDT releases (and contribute back to the open source CDT). Alternatively, some of those vendors have a forked CDT so they may be able to cherry-pick this change into one of their releases sooner than they can do a full upgrade.
Comment 53 Greg Willits CLA 2021-06-21 17:43:06 EDT
(In reply to Jonah Graham from comment #52)
> (In reply to Greg Willits from comment #51)
> > @Jonah — So, a question. The programming for the feature gets done,
> > eventually it ships...
> 
> Yup - aiming to have this available in the next milestone build (early July)
> and have it released along with 2021-09 release in Sept.

Nice.


> > For now, I'm wondering (more theoretically vs a request) if this can be
> > delivered as a plugin which should work with such 3rd party versions
> > (Siemens/Mentor, STM, etc.)
> 
> Short answer is not a chance :-)
> The best thing to do is...

OK, fair enough.
Comment 54 Greg Willits CLA 2021-06-21 18:41:41 EDT
Possibly another detail to contend with...

gcc -Wno-unknown-pragmas

A long time ago, when I moved my Xcode files to an older Eclipse, warnings were generated for the pragmas. I ended up using the hack of an #ifndef MARK wrapper around my marks to prevent compiler warnings. I now know that the above option exists.

I just played with it, and realized that removing my #ifndef hack results in no complaints even if I do not specify the above -W.

Anyway, I started out wondering if perhaps the above option now needs to be added to the GUI at Properties > C/C++ Build > Settings > GCC C Compiler > Warnings as "Ignore unknown pragmas" or something -- but it's looking like it is already included somewhere by default.

Thought I'd mention it just in case it was something to verify.
Comment 55 Eclipse Genie CLA 2021-07-11 16:53:26 EDT
New Gerrit change created: https://git.eclipse.org/r/c/cdt/org.eclipse.cdt/+/182960
Comment 59 Jonah Graham CLA 2021-07-12 09:58:11 EDT
The change is in! N&N needs to be updated and the 2021-09 M1 (CDT 10.4.0 M1) release due this week will have this change.


(In reply to Greg Willits from comment #54)
> Possibly another detail to contend with...
> 
> gcc -Wno-unknown-pragmas

If a user needs it the -Wno-unknown-pragmas can be added to extra flags in the settings. I will make a note of it in the N&N
Comment 60 Jonah Graham CLA 2021-09-15 10:30:13 EDT
N&N updated.