[gnome-latex] hacking: add note about AST

[Sébastien Wilmet <swilmet src gnome org>]

commit 4084e36785e1bac261858eb34b2eba098cd06ed0
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Tue Jul 30 12:14:22 2019 +0200

    hacking: add note about AST
    
    Current content of
    https://wiki.gnome.org/Projects/GtkSourceView/CodeFolding
    (Gtef has now been renamed to Tepl). To have a backup of that wiki page.
    
    = Code Folding =
    
    [[GnomeBug:775751|Bug #775751]]
    
    Implemented incrementally in [[Projects/Gtef|Gtef]].
    
    == Proposal 1 ==
    
    === GtefGutterRendererFolds ===
    
    '''First iteration done.'''
    
    Implement a basic gutter renderer for the drawing. This gutter renderer would be at the same level as 
!GtkSourceGutterRendererPixbuf and !GtkSourceGutterRendererText.
    
    Initially public, might become private in the future.
    
    === GtefFoldRegion ===
    
    '''First iteration done.'''
    
    Simple class that represents a region in a !GtkTextBuffer that can be folded.
    
    To fold the region, uses internally a !GtkTextTag with the invisible property. But in the API only 
!GtkTextIters are exposed. !GtkTextMarks can be used to store the start/end (or store with a !GtkTextTag, but 
this is less convenient).
    
     * new(buffer, start, end);
     * get_bounds();
     * set_bounds();
     * get_folded();
     * set_folded();
     * gboolean folded property.
    
    === GtefFolding ===
    
    A n-ary tree of !FoldRegions. Uses internally a GNode, and keep the !FoldRegions sorted.
    
    To implement code folding for a specific language (e.g. XML), a class needs to be written that fills and 
adapt the !GtefFolding tree. That class needs to listen to the insert-text and delete-range buffer signals, 
and adapt the !GtefFolding object accordingly, creating and destroying !FoldRegions. I think it gets a bit 
tricky when the user is editing the text and the tree is temporarily broken (an invalid XML file).
    
     * add_fold_region();
     * remove_fold_region(bool remove_all_children);
     * get_fold_regions_at_iter();
     * get_fold_regions_in_range();?
     * get_parent(folding, fold_region);
     * get_direct_children(folding, fold_region);
     * ...
    
    === GtefGutterRendererFolding ===
    
    Subclass of !GtefGutterRendererFolds. Do the connection with a !GtefFolding object. At the same level as 
!GtkSourceGutterRendererMarks and !GtkSourceGutterRendererLines.
    
    Probably private.
    
    === In GtefBuffer ===
    
    Be able to get/set the !GtefFolding object.
    
    === In GtkSourceView ===
    
    Be able to show/hide the !GtefGutterRendererFolding.
    
    == Proposal 2 ==
    
     * Instead of !GtefFolding tree, have a more general !GtefAst (Abstract Syntax Tree).
     * Instead of !GtefFoldRegion, have a more general !GtefAstElement with a `foldable` property.
    
    Applications could create subclasses of !GtefAstElement for different kinds of elements, providing more 
functions.
    
    The !GtefAst could be used to display some of the element types in a !GtkTreeView (e.g. in a side panel). 
Either as a tree (e.g. document structure: chapters, sections, sub-sections, …), or a list (e.g. list of 
functions).
    
    The idea is to create and maintain a single AST (per !GtkTextBuffer) that can be used for different 
features. For the code folding, we are interested only by the foldable !GtefAstElements. Similarly, for the 
side panel we might be interested only by some element types, not all.
    
    Gtef would provide the basic infrastructure, the hard part would be to create the parser that builds the 
AST, and update it on text insertions/deletions, and needs to deal with invalid content when the text is 
being edited.

 HACKING | 9 +++++++++
 1 file changed, 9 insertions(+)
---
diff --git a/HACKING b/HACKING
index a9f5394..d0bdb0c 100644
--- a/HACKING
+++ b/HACKING
@@ -31,6 +31,15 @@ For gnome-latex, if the build tools break in the future, a solution is to
 create a container with an older version of TeX Live bundled (or at least an
 older version of latexmk bundled).
 
+For the file structure in the side panel, a better implementation would be to
+maintain an AST (Abstract Syntax Tree) attached to the GtkSourceBuffer, and by
+using GtkSourceRegion. Then this AST can serve for other features, especially
+for the auto-completion, or for text folding. For a project with multiple *.tex
+files, the AST can be created for files not yet opened in the application; this
+would be useful to provide completion for the \ref, \pageref and \cite
+commands. See also the Proposal 2 at:
+https://wiki.gnome.org/Projects/GtkSourceView/CodeFolding
+
 Previous content of this file:
 ==============================