Replies: 1 comment 7 replies
-
Whenever I write an article in PML I use several files in a single directory or a directory tree, where sub-directories represent parent chapters. Having small files makes it easier to maintain them and move chapters around. See example of a directory tree. Therefore I would expect symbols to be indexed globally.
Yes, and a analogous case in PML would be this: A parameter is defined in file A, and I want to use it in file B. Or: File C contains an internal link (xref) to a chapter in file D.
I agree. Sometimes people will of course use just one file for an article (e.g. small article), and then indexing globally might be overkill. As so often, there is no one-size-fits-all solution. But most users would probably prefer global indexing.
That's a good question. I don't have enough experience myself to confidently answer this, but I would say that at a minimum, all parameters and all nodes that have an explicit id (e.g. |
Beta Was this translation helpful? Give feedback.
-
@pml-lang and @celtic-coder, I wanted to share with you some thoughts on Symbols indexing, and get your feedback on the issue.
Currently, Sublime PML is indexing all symbols only locally (i.e. for the specific file in which they occur). Sublime Text allows indexing a Symbol either locally or globally (for the whole Project), or both.
The idea is that in multi-file sources, e.g. a C/C++ project, you might want be able to jump to a symbol definition (e.g. a function) even if the definition is in another file within the Project. On the other hand, when dealing with documents you usually want to index title headings only locally to the file in which they are found.
With PML it's hard to make a clean cut decision, because the
[insert
node allows to include external PML docs into each other, a feature which is probably much used in large document project (e.g. splitting a document by chapters).I think the question is whether to index symbols only locally or both locally and globally (local indexing seems to be always necessary, I can't think of any valid exceptions rights now).
On the user side, Sublime Text allows to quickly navigate through either local symbols or global symbols.
The Symbols panel will show all indexed symbols, not just PML's symbols (e.g. markdown symbols, including headings, and tokens from the various programming languages inside the project). For this reason, adding any Symbol to the Global Index can quickly lead to index pollution, although filtering through the desired results should be quite easy, especially since Sublime PML adorns PML symbols by manipulating their appearance.
In my opinion, Chapter titles should only be indexed locally, even though some projects do split chapters across different files it probably makes little sense to index them globally. But I might be wrong on this, for I haven't yet worked on big PML documentation projects — so it's an open issue for now.
I'm also inclined to believe that parameters (occurrences and definitions alike) should be indexed both locally and globally, for I foresee that defining their values in a commonly shared file is going to be a common strategy, so it's going to be useful to be able to jump to their definition, even if in an external file (or more than one, in case of conditional inclusion of one or the other).
In any case, it's worth noting that ST always allows to lookup just the local Symbols index (CtrlR), so global indexing doesn't prevent local lookup operations.
I'd like to ear your thoughts and ideas on this, and what you envision would be the optimal editing experience when it comes to deciding which symbols (nodes, attributes) are worth indexing and how, and which potential features might be built around them.
Beta Was this translation helpful? Give feedback.
All reactions