In order to support source browsing w/o cluttering the UI with many editor tabs,
we need to provide an API for opening editor in tab-reusal mode.
Opening an editor in tab-reusal mode would mean:
1. In case the editor is already opened, just switch to it.
2. If there is a tab-reusal editor opened already, replace it with the
to-be-opened editor and switch to it.
3. Open a new editor and mark it for tab-reusal.
4. If the editor is modified, unmark it for tab-reusal.

I'm proposing to add Line.SHOW_REUSE constant for Line.show() method and change
the implementation of Line.show() so that it adheres to the abovementioned
semantics.
I'll attach a diff with changes both in API and implementation, and the
apichanges as well.
The implementation partially depend on issue 94604 (due in 6.0M8) for "nice"
behaviour. I can emulate the behaviour so the API and somehow working
implementation is ready around M7 for waiting API clients, but the
implementation might move the tab position on editor reuse.

I think the change is looking good, just a few things:
VS1: (nit-pick) Could you please javadoc all params of openAtImpl? I know the
method is private, but since you have chosen to write javadoc for it you should
document all its parameters.
VS2: Will it be possible to forcibly change the reusable-editor, ie. unmark the
existing one and open a new one? Here is the usecase: You've browsed through
some files and then you realize that the file you are currently looking at is
actually important and you want to keep it around, but you also want to browse
further to another file. This is pretty common situation I think and the
solution for it could be the same as what web browsers do - 'Open Link in New
Tab'. We could enhance navigation actions in the editor module to support that,
but we would need to tell openide/text to stop using the current
reusable-editor, leave it as it is and open a new one. Is this a reasonable
usecase? Is it addressed somehow or can we address it please?
The following questions do not concern the API, so the answers are not really
important for the review, but I'll ask anyway.
VS3: Shouldn't the decision whether the reusable-editor can or cannot really be
reused be done at the time when somebody really wants to reuse it instead of
making this decision at the time when the file in the reusable-editor is
modified? Making the decision later could probably streamline the browsing even
more - eg. you browse to a file, fix a typo in javadoc, save the file and browse
to another one, for example.
VS4: Will it be possible for a user to distinguish the reusable-editor-tab from
normal editors in UI?
Thanks.

-> VS01: copy/paste issue. @since tag doesn't belong there either ;-)
-> VS02: Not currently addressed. I forgot to mention this change is going to be
complemented with great improvements in editor history (ccing Mila in case he's
not on the reviewers), so you can easily return to the file through a combo box.
Also, as you realized,once you touch the file, it would stick. Should this
became broader concern, we can either add new constant(_NEW_REUSE) or provide a
semantic shift that e.g. if the currently reusable editor gets requested again
in different mode (SHOW_GOTO), it switches to non-reusable.
-> VS03: Good comment. I was thinking about this when implementing, but HIE
recommendation was keep the file even after saved, so I implemented it the
easiest way. Otherwise I'd have to keep a flag per editor or something. Talk to
HIE if you feel strognly about this.
-> VS04: Wasn't planned. Again, ask HIE, it may be nice if e.g. the reusable
editor tab is slightly colored if that would be possible.

Jesse, you can apply the attached patch and sed s/SHOW_GOTO/SHOW_REUSE/ in
java/source/src/org/netbeans/api/java/source/UiUtils.java.
This will cover Alt+G but AS-O as well though, which may be more that what want.

-> VS02: OK, we need to iron out the semantics of _NEW_REUSE. Imagine the
following situation:
Two tabs: /reusable(1.java)] /selected(2.java)]
user tries to navigate ("open in new tab") to 3.java.
Should we
A) unmark 1.java and open new 3.java
B) replace 1.java with 3.java
Both seem slightly wrong as A doesn't take the opportunity of reusing reusable
tab (the user intention was in fact "keep this", not "open new"), while B is not
opening in "new" tab). I'd personally vote for B, but as Dafe often says, I'm
not a representative sample ;-)

-> VS02. I think the behavior could be moved on client of this API.
i.e. I vote for the browser approach:
- In browser when you left click on link, usually current page is reused, but
sometimes new page is opened (in our case - analog of "not saved editor" tab).
- when you middle click - new tab is always opened, not any other "reusable" is
reused

An idea which may or may not be related, and maybe belongs more on nbui than an
API review: Firefox with the Tab Mix Plus extension has the nice behavior that
if you have a bunch of tabs open, and you are working in some tab somewhere in
the middle, any requests to open a new tab will open it right next to the one
you have selected, not at the end. This tends to keep related things together.
(More precisely, for every time interval during which you do not switch tabs,
all new tab requests are opened in sequence to the right of the selected tab. So
a new tab may not be directly adjacent to the selected tab, but it will
generally be nearby.) I actually don't so much mind NetBeans opening new tabs
when I use Alt-G, as I mind those tabs being dumped way to the right of my
(often long) tab list, so that I can't even see the original tab.

I like Jesse's idea, it seems reasonable to open tabs 'nearby' the currently
selected tab. But it looks orthogonal to VS02 and perhaps this whole issue,
which is not to say that we should ignore it or loose it.
-> VS02: Petr's example - I tend to think that A is a little bit more
consistent, because the 'Open in new tab' will always do the same no matter
where you invoke it. In option B if 'Open in new tab' starts in the reusable
tab, the action will in fact unmark the tab and open a new one, right? But
that's exactly what A does.
-> VS02: Vladimir, I agree with you, clients (read editor) will have to handle
middle clicks and/or add 'Open in new tab' action, but the openning itself is
controlled by openide/text and the clients will need to be able to say that a
file should be opened in a 'new' reusable tab (even if one is already opened and
could be reused).
VS05: Just a question: how is TopComponent cloning going to work for the
reusable tab?

-> VS02: you're right, unless you think the user's motivation for choosing "open
in new tab" was in fact: "Keep current tab open (no matter it it's reusable or
not)". I'll try to describe the behavior in tests.
-> VS05: If you make a clone, it certainly won't be reusable (you did explicitly
spent too much effort on playing with the tab already). The original might be
reused subsequently though. Switching to a clone is the same as currently -
already open (one of them), keep the reusable marker on the originally reusable tab.

Committed while still using temporal TC replacement, so the reused editor window
would "move" to the last position. (Still waiting for #94604)
openide/text/apichanges.xml,v1.18
openide/text/manifest.mf,v1.16
openide/text/src/org/openide/text/CloneableEditorSupport.java,v1.30
openide/text/src/org/openide/text/EditorSupportLineSet.java,v1.4
openide/text/src/org/openide/text/Line.java,v1.5
openide/text/test/unit/src/org/openide/text/ReusableEditorTest.java,v1.1

Now it finally works as expected, no tab movement:
openide/text/manifest.mf,v1.17
openide/text/nbproject/project.xml,v1.14
openide/text/src/org/openide/text/CloneableEditorSupport.java,v1.31
Whoever wants to be sure about correct behavior should depend on openide-text/6.15