How to write readable source files?

Jan U. Hasecke

24 Apr 2021 24 Apr '21

9:45 a.m.

Hi all, how do you format your ConTeXt source files? I recently discovered prettier which reformats source files for different markup and programming languages such as html, markdown, json etc. There are some other tools around but I don't find anything for ConTeXt. Do you know of any prettifying tool? Is there a best practice for ConTeXt source files, at all? Ciao! Jan Ulrich Hasecke

Show replies by date

Henning Hraban Ramm

24 Apr 24 Apr

11:55 a.m.

...

Am 24.04.2021 um 11:45 schrieb Jan U. Hasecke :

Do you know of any prettifying tool?

I don’t know one.

...

Is there a best practice for ConTeXt source files, at all?

I guess many of us adhere to Hans’ style, as shown in the sources. i.e. e.g. \setupsomething [name] [key=value, otherkey=value] while I prefer: \setupsomething[name][ key=value, otherkey=value, ] That looks clearer to me and works a bit better with automatic indenting in editors. But source code formatting is a matter of taste in most cases. Hraban

Hans van der Meer

1:25 p.m.

...

...
Is there a best practice for ConTeXt source files, at all?

Readable code is not just about formatting. Adding clear and complete comments that document the code can be considered even more important. dr. Hans van der Meer

...

On 24 Apr 2021, at 13:55, Henning Hraban Ramm wrote:

...
Am 24.04.2021 um 11:45 schrieb Jan U. Hasecke :

Do you know of any prettifying tool?

I don’t know one.

...
Is there a best practice for ConTeXt source files, at all?

I guess many of us adhere to Hans’ style, as shown in the sources.

i.e. e.g. \setupsomething [name] [key=value, otherkey=value]

while I prefer:

\setupsomething[name][ key=value, otherkey=value, ]

That looks clearer to me and works a bit better with automatic indenting in editors.

But source code formatting is a matter of taste in most cases.

Hraban ___________________________________________________________________________________ If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context webpage : http://www.pragma-ade.nl / http://context.aanhet.net archive : https://bitbucket.org/phg/context-mirror/commits/ wiki : http://contextgarden.net ___________________________________________________________________________________

juh

1:45 p.m.

Am Sat, Apr 24, 2021 at 01:55:28PM +0200 schrieb Henning Hraban Ramm:

...

I guess many of us adhere to Hans’ style, as shown in the sources.

i.e. e.g. \setupsomething [name] [key=value, otherkey=value]

while I prefer:

\setupsomething[name][ key=value, otherkey=value, ]

I, too, stick to these styles more or less. But after many iterations my code gets scrambled so that I would be happy to reformat it via some tool. The usual functions in Vim and Emacs never results in a style like this. Ciao! Jan Ulrich Hasecke -- Autoren-Homepage: ......... http://literatur.hasecke.com Satiren & Essays: ......... http://www.sudelbuch.de Privater Blog: ............ http://www.hasecke.eu Netzliteratur-Projekt: .... http://www.generationenprojekt.de

Nicola

7:25 p.m.

On 2021-04-24, juh wrote:

...

Am Sat, Apr 24, 2021 at 01:55:28PM +0200 schrieb Henning Hraban Ramm:

...
I guess many of us adhere to Hans’ style, as shown in the sources.

i.e. e.g. \setupsomething [name] [key=value, otherkey=value]

while I prefer:

\setupsomething[name][ key=value, otherkey=value, ]

I, too, stick to these styles more or less.

But after many iterations my code gets scrambled so that I would be happy to reformat it via some tool. The usual functions in Vim and Emacs never results in a style like this.

I maintain the ConTeXt plugin for Vim. Currently, there are no indentation rules (except for embedded MetaPost code), and that is intentional: as the examples above show, there is no commonly accepted indentation style, so forcing one on the user is not a good idea. That said, if you have a list of desiderata, I may consider adding an option to enable them. You may open an issue here for further discussion: https://github.com/lifepillar/vim-context-metapost If you need to reflow paragraphs, the plugin provides the tp text object. So, for instance, you may type gqtp to reformat the current paragraph (with hard breaks) using the current textwidth. Nicola

juh

25 Apr 25 Apr

7:13 a.m.

Hi Nicola, Am Sat, Apr 24, 2021 at 07:25:27PM -0000 schrieb Nicola:

...

I maintain the ConTeXt plugin for Vim. Currently, there are no indentation rules (except for embedded MetaPost code), and that is intentional: as the examples above show, there is no commonly accepted indentation style, so forcing one on the user is not a good idea.

I am married to Emacs but have an affair with Vim. ;-) I use it from time to time including your plugin. I don't have a strong opinion about indentation. So I won't mind if a tool would just do it for me. But I understand your point. And I tend to say that not indenting text between start-stop-commands is the way I want my text. I don't like to reflow paragraphs as I want to have one line for each sentence. This is my only opinion about formatting text. Not indenting is a good idea because sometimes I have really long lines and identation would make them even longer. I real IDE-like support for ConTeXt would be nice: setup-en.pdf is always open when I write environments as I cannot remember all commands and options. If my editor would give me a list of possible commands when I just type some letters and then give possible options when I edit inside a command – that would be great. Thanks a lot for your help Jan Ulrich Hasecke -- Autoren-Homepage: ......... http://literatur.hasecke.com Satiren & Essays: ......... http://www.sudelbuch.de Privater Blog: ............ http://www.hasecke.eu Netzliteratur-Projekt: .... http://www.generationenprojekt.de

Nicola

12:12 p.m.

On 2021-04-25, juh wrote:

...

I am married to Emacs but have an affair with Vim. ;-)

Eventually, you will abandon the dark side of the Force ;-)

...

I real IDE-like support for ConTeXt would be nice: setup-en.pdf is always open when I write environments as I cannot remember all commands and options. If my editor would give me a list of possible commands when I just type some letters and then give possible options when I edit inside a command – that would be great.

If there is a way to automatically get a list of all ConTeXt commands and options (and, ideally, MetaFun defs, types, and other keywords), I'd be happy to improve omni-completion for ConTeXt in Vim. Nicola

Hans Hagen

12:24 p.m.

On 4/25/2021 2:12 PM, Nicola wrote:

...

On 2021-04-25, juh wrote:

...
I am married to Emacs but have an affair with Vim. ;-)

Eventually, you will abandon the dark side of the Force ;-)

...
I real IDE-like support for ConTeXt would be nice: setup-en.pdf is always open when I write environments as I cannot remember all commands and options. If my editor would give me a list of possible commands when I just type some letters and then give possible options when I edit inside a command – that would be great.

If there is a way to automatically get a list of all ConTeXt commands and options (and, ideally, MetaFun defs, types, and other keywords), I'd be happy to improve omni-completion for ConTeXt in Vim. All is in xml files (i-*.xml) in the distribution maintained by Wolfgang. We ship with this for editors:

...

dir t:\texmf\context\data

04/21/2021 11:40 AM <DIR> scite 04/21/2021 11:40 AM <DIR> textadept 04/21/2021 11:40 AM <DIR> texworks 04/21/2021 11:40 AM <DIR> vscode these lists are generated by mtx-interface so we can add more if needed Hans ----------------------------------------------------------------- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl -----------------------------------------------------------------

Nicola

29 May 29 May

3:03 p.m.

On 2021-04-25, Hans Hagen wrote:

...

...
If there is a way to automatically get a list of all ConTeXt commands and options (and, ideally, MetaFun defs, types, and other keywords), I'd be happy to improve omni-completion for ConTeXt in Vim. All is in xml files (i-*.xml) in the distribution maintained by Wolfgang. We ship with this for editors:

...
dir t:\texmf\context\data

04/21/2021 11:40 AM <DIR> scite 04/21/2021 11:40 AM <DIR> textadept 04/21/2021 11:40 AM <DIR> texworks 04/21/2021 11:40 AM <DIR> vscode

these lists are generated by mtx-interface so we can add more if needed

Could you please elaborate on the (automatic?) data flow from ConTeXt's source files to data files for each application? Is it: source code -> XML -> .lua -> mtx-interface -> data? In particular, it is not clear to me how i-*.xml files are related to mtx-interface, as the latter does not use them directly, AFAICS. Anyway, mtx-interface seems exactly what I am looking for, and I would like to use it to generate ConTeXt keywords for Vim. Can I patch that script? For MetaFun keywords I don't know yet: do those XML files contain enough information about the content of all mp-* source files? E.g., the fact that `hlingrid` is a def? Looking at the Scite files, I see only internals and commands, and they seem to cover only the "main" MetaFun names. I have used a custom script in the past for fine-grained keyword extraction from MetaFun's source code. By fine-grained, I mean that the output contains information about the kind of keyword (def, primary def, vardef, constant, variable, etc.) I could update it to Lua and mp-*.mpxl if that interests you—unless that has already been done, of course. Nicola

Hans Hagen

5:08 p.m.

On 5/29/2021 5:03 PM, Nicola wrote:

...

On 2021-04-25, Hans Hagen wrote:

...
...
If there is a way to automatically get a list of all ConTeXt commands and options (and, ideally, MetaFun defs, types, and other keywords), I'd be happy to improve omni-completion for ConTeXt in Vim. All is in xml files (i-*.xml) in the distribution maintained by Wolfgang. We ship with this for editors:

...
dir t:\texmf\context\data

04/21/2021 11:40 AM <DIR> scite 04/21/2021 11:40 AM <DIR> textadept 04/21/2021 11:40 AM <DIR> texworks 04/21/2021 11:40 AM <DIR> vscode

these lists are generated by mtx-interface so we can add more if needed

Could you please elaborate on the (automatic?) data flow from ConTeXt's source files to data files for each application? Is it:

source code -> XML -> .lua -> mtx-interface -> data?

In particular, it is not clear to me how i-*.xml files are related to mtx-interface, as the latter does not use them directly, AFAICS.

for sure it does in the early days of context mkii we had \startsetups kind of definitions that got filtered from the source but when xml support was built that moved to an xml file then Wolfgang did an excellent job on checking each xml snippet and added many more and these i-* files showed up, we extended the xml a bit, redid the rendering of these lists etc wolfgang is in charge of this so when something specific in the files is needed ...

...

Anyway, mtx-interface seems exactly what I am looking for, and I would like to use it to generate ConTeXt keywords for Vim. Can I patch that script?

basically we only need function flushers.vim(collected) end

...

For MetaFun keywords I don't know yet: do those XML files contain enough information about the content of all mp-* source files? E.g., the fact that `hlingrid` is a def? Looking at the Scite files, I see only internals and commands, and they seem to cover only the "main" MetaFun names.

it is still on the agenda to make xml files for metafun but there is no timeline for that now, when it comes to highlighting, the reference is the scite one (which supports several of the languages that we use, and also supports mixed lua/mp/tex/... lexing) ... right from the start the way it shows up in an editor determined how the user interface evolved ... believe it or not, but for a long time we used texedit (written in modula, was pretty ok in 640K mem, also fast and one could scroll files in the sidebar and see them instantly; it used the character based windowing i'd written as a student for terminals connected to a dec vax .. just for fun ... i'm that old) ... when modula disappeared i actually rewrote that one in perl/tk and it still works but then decided to use scite anyway, so scite is still my reference (i looked to vscode but seeing all this extra stuff, the need for 'servers', the lack of simply running a command based on suffix ... not now) that said, we can support whatever editor one uses makes much sense (one should really use the editor, word processor, operating system etc one feels most comfortable with) so just make a prototype (or tell me what kind of lists you need, because it's rather trivial to generate them)

...

I have used a custom script in the past for fine-grained keyword extraction from MetaFun's source code. By fine-grained, I mean that the output contains information about the kind of keyword (def, primary def, vardef, constant, variable, etc.) I could update it to Lua and mp-*.mpxl if that interests you—unless that has already been done, of course. just look at the files in the scite path ... much info is available, for context it comes from the xml files, for the tex engine and meta* it comes from mult* lua files

adding more detail (not sure if distinguishing between def and vardef makes sense ... we more use the 'primitive', 'lowlevel', 'interface' kind of grouping let's see what Wolfgang thinks of it ... Hans ----------------------------------------------------------------- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl -----------------------------------------------------------------

Nicola

6:29 p.m.

On 2021-05-29, Hans Hagen wrote:

...

On 5/29/2021 5:03 PM, Nicola wrote:

...
...
these lists are generated by mtx-interface so we can add more if needed

Could you please elaborate on the (automatic?) data flow from ConTeXt's source files to data files for each application? Is it:

source code -> XML -> .lua -> mtx-interface -> data?

In particular, it is not clear to me how i-*.xml files are related to mtx-interface, as the latter does not use them directly, AFAICS.

for sure it does

Ok, my cursory look was then… too cursory. I'll dig better.

...

...
Anyway, mtx-interface seems exactly what I am looking for, and I would like to use it to generate ConTeXt keywords for Vim. Can I patch that script?

basically we only need

function flushers.vim(collected) end

Ok.

...

...
For MetaFun keywords I don't know yet: do those XML files contain enough information about the content of all mp-* source files? E.g., the fact that `hlingrid` is a def? Looking at the Scite files, I see only internals and commands, and they seem to cover only the "main" MetaFun names.

it is still on the agenda to make xml files for metafun but there is no timeline for that

So, is it correct that the XML files are automatically generated from the source code, and kept in sync with it? If so, how is that done? Or are they manually curated? I'd be willing to contribute to make progress on the MetaFun part.

...

just look at the files in the scite path ... much info is available, for context it comes from the xml files, for the tex engine and meta* it comes from mult* lua files

Ok, I'll look there.

...

adding more detail (not sure if distinguishing between def and vardef makes sense ... we more use the 'primitive', 'lowlevel', 'interface' kind of grouping

Whatever you think is more appropriate... Provided that it can be parsed automatically. Nicola

Hans Hagen

11:04 p.m.

On 5/29/2021 8:29 PM, Nicola wrote:

...

So, is it correct that the XML files are automatically generated from the source code, and kept in sync with it? If so, how is that done? Or

the xml files are maintained by Wolfgang who knows context inside out and has ways to keep track of additions (although some commands became obsolete when we went mkiv, like those dealing with font encoding and so) we're mostly talking about additions

...

are they manually curated? I'd be willing to contribute to make progress on the MetaFun part.

ok, but let's first wait what Wolfgang says .. we probably first have to check if we need to add some to the xml definitions (btw, the lmt metapost commands i.e. the key/value macros fit in well in the optional argument appeoach, the more low level ones more resemble the low level context commands for which we have specific definitions)

...

Whatever you think is more appropriate... Provided that it can be parsed automatically. so what does vim expect? isn't there some kind of common format for lexers?

Hans ----------------------------------------------------------------- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl -----------------------------------------------------------------

Nicola

30 May 30 May

8:13 a.m.

On 2021-05-29, Hans Hagen wrote:

...

so what does vim expect? isn't there some kind of common format for lexers?

The output I need is very simple: syn keyword Group1 <keyword1> <keyword2> ... syn keyword Group2 <keyword1> <keyword2> ... ... where Group1, Group2, ... define arbitrary groups of keywords. For instance, for MetaFun I currently have `mpDef` (MetaPost def macro), `mpVardef` (MetaPost vardef), `mpPrimaryDef`, `mpSecondaryDef`, `mpTertiaryDef`, `mpCommand`, `mpConstant`, `mpVariable`, `mpType`, `mpNewInternal`, and a few others. An excerpt from the current syntax file looks like this: ... " mp-base.mpiv syn keyword mpNumExp graypart syn keyword mpType graycolor greycolor syn keyword mpConstant cyan magenta yellow " mp-butt.mpiv syn keyword mpDef predefinedbutton some_button syn keyword mpConstant context_butt " mp-char.mpiv syn keyword mpDef flow_begin_chart flow_begin_sub_chart syn keyword mpDef flow_chart_draw_comment flow_chart_draw_exit ... syn keyword mpVardef flow_xy_on_grid flow_xy_right flow_xy_top syn keyword mpVardef flow_y_on_grid syn keyword mpVariable flow_arrowtip flow_chart_background_color syn keyword mpVariable flow_chart_offset flow_comment_offset syn keyword mpVariable flow_connection_arrow_size ... This fine-grained classification allows for great flexibility when defining syntax highlighting, because each group can have different properties (and the user can customize that), although by default several groups are highlighted in the same way (e.g., all macros have the same highlighting by default). Nicola

luigi scarso

24 Apr 24 Apr

12:12 p.m.

On Sat, Apr 24, 2021 at 11:53 AM Jan U. Hasecke wrote:

...

Hi all,

how do you format your ConTeXt source files?

I recently discovered prettier which reformats source files for different markup and programming languages such as html, markdown, json etc.

There are some other tools around but I don't find anything for ConTeXt.

Do you know of any prettifying tool?

Is there a best practice for ConTeXt source files, at all?

you should consider that in TeX (but also in Python, for example) spaces matter. Sometimes unwanted results are triggered by unseen blanks, and they are hard to discover. -- luigi

Hans Hagen

3:17 p.m.

On 4/24/2021 11:45 AM, Jan U. Hasecke wrote:

...

Hi all,

how do you format your ConTeXt source files?

I recently discovered prettier which reformats source files for different markup and programming languages such as html, markdown, json etc.

There are some other tools around but I don't find anything for ConTeXt.

Do you know of any prettifying tool?

Is there a best practice for ConTeXt source files, at all?

most of the documentation files are ok actually i often spend quite some time on formatting because inconstent formatting for sure leads to errors .. .keep in mind that in tex spaces and empty lines often matter if you use the scite lexer (in verbatim) you also get an idea how I see the source Hans ----------------------------------------------------------------- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl -----------------------------------------------------------------

1302

Age (days ago)

1338

Last active (days ago)

List overview

Download

14 comments

7 participants

participants (7)

Hans Hagen
Hans van der Meer
Henning Hraban Ramm
Jan U. Hasecke
juh
luigi scarso
Nicola