Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Starting of the Documentation #1961

Closed
wants to merge 27 commits into from
Closed

Starting of the Documentation #1961

wants to merge 27 commits into from

Conversation

TornaxO7
Copy link
Contributor

Currently added

  • Added Table of Contents in the CONTRIBUTE.md file
  • Added new section: 'Documentation'
    => Added a little file structure

Information

The documentation isn't finished yet! I'll tell you if it's finished. I just wanted to start the pull request, so you can see "live" each commit and be able to review it immediately. I thought, that it might suit, if I ask some question here, instead of creating a new issue everytime. So "all" questions about the code will be here. Is that okay for you?

- Added Table of Contents in the CONTRIBUTE.md file
- Added new section: 'Documentation'
    => Added a little file structure
@TornaxO7
Copy link
Contributor Author

TornaxO7 commented Feb 16, 2021

Codequestion

So here comes the first question: In your vimtex#options#init() you're calling a lot of init-script-functions. Did you wrote them all at a specifique file or do I have to find them on my own? Because otherwise I'm gonna use grep to find each implementation of the function xD

EDIT
Oh wait. I'm dumb, the functions are written below the vimtex#options#init() function.... sorry! My mistake.

- Started description of the vimtex#init() function.
@TornaxO7
Copy link
Contributor Author

Hmm.... I'm not sure, but if I continue like that, the documentation might be too detailed (I think). What do you think @lervag ? Because I think that it's easy to understand, what the vimtex#options#init() function does. So one to 3 sentences should be fine.

@lervag
Copy link
Owner

lervag commented Feb 18, 2021

I thought, that it might suit, if I ask some question here, instead of creating a new issue everytime. So "all" questions about the code will be here. Is that okay for you?

Yes, that's sensible, thanks!

Hmm.... I'm not sure, but if I continue like that, the documentation might be too detailed (I think). What do you think @lervag?

Yes, I think so too. I think one should aim for more or less self-documented code (although that is of course very hard). Avoid too many side effects, use good variable and function names, consistent styles, and so on. And if needed, one should comment things within the code of course.

I think the extra documentation we are discussing now should focus more on the structure and "architecture" than on the detailed level of the code. But still, I do see clear value in making the code more available through some high-level documentation, so thanks for starting this work!

CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Outdated
│   └── tex.vim
├── test
└── xclip
```
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem with adding a listing like this is that it quickly becomes out-of-date because I (and other contributors) will forget to update it. Do we really need to list all of this?

What's the main intent? Perhaps the structure? How about taking it one step back and instead explain the intent of the directories themselves, and not the individual files? We can point the user to the relevant sections in the vim help docs (e.g. :help autoload, :help ftdetect, etc).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem with adding a listing like this is that it quickly becomes out-of-date because I (and other contributors) will forget to update it. Do we really need to list all of this?

You're right. I've got another idea: Let's create a table of contents, which should represent the directory-structure of VimTex. So if someone VimTex/autoload/vimtex/compiler, than he/she just needs to click on this path in the TOC and gets a short description about the directory.

How about taking it one step back and instead explain the intent of the directories themselves, and not the individual files?

Aye!

We can point the user to the relevant sections in the vim help docs (e.g. :help autoload, :help ftdetect, etc).

Yes, I'd also like to add a link to this awesome book which taught me vimscript ;)

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right. I've got another idea: Let's create a table of contents, which should represent the directory-structure of VimTex. So if someone VimTex/autoload/vimtex/compiler, than he/she just needs to click on this path in the TOC and gets a short description about the directory.

I'm not sure I fully understand... "So if someone VimTex/autoload/vimtex/compiler" - I think you forgot a verb in the sentence...?

Yes, I'd also like to add a link to this awesome book which taught me vimscript ;)

Yes, feel free to add a link in the code documentation resource. I agree it is a good resource!

CONTRIBUTING.md Outdated
```
So how does vimtex start? Well, it calls the `vimtex#init()` function at the
beginning, if you open a `tex` or a `bib` file (see in `ftplugin`). So let's
take a look, how vimtex initialises:
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I propose to make initialization into a sub section.

CONTRIBUTING.md Outdated
use the color of a vim-error-msg for all vimtex errors).
2. Warn the user, if he/she is using deprecated settings
3. Save the settings of vimtex which are provided from the user or load its
default values (like `g:vimtex_compiler_enabled`)
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is going in the right direction. The vimtex#options#init() is made available like this because I realized I sometimes needed it even when not really loading the full plugin (e.g. if you only want the syntax highlighting part).

I think I would say that setting the options are the main part and should be number 1 here, while defining highlight groups is "less important". Also, it is important to use correct names here: there is no such thing as vim-error-msg. There is a group called VimtexError, though.

CONTRIBUTING.md Outdated
├── test
└── xclip
```
So how does vimtex start? Well, it calls the `vimtex#init()` function at the
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please note that the plugin should be referred to as VimTeX (see latest release notes). :)

@TornaxO7
Copy link
Contributor Author

Ok, I added the DOCUMENTATION.md.

I'm not sure I fully understand... "So if someone VimTex/autoload/vimtex/compiler" - I think you forgot a verb in the sentence...?

The table of contents represents what I meant and you're right, I meant So if someone wants to know something about vimtex/autoad/vimtex/compiler, but I forgot the other half of my sentence xD.

@TornaxO7
Copy link
Contributor Author

Oh no, I did git fetch before to be up to date (I thought that it wouldn't be bad, if I would do that ._.). Should I create a new pull request/branch or it fine for you (or do you have an idea, how I can fix that?)?.

@lervag
Copy link
Owner

lervag commented Feb 24, 2021

Oh no, I did git fetch before to be up to date (I thought that it wouldn't be bad, if I would do that ._.). Should I create a new pull request/branch or it fine for you (or do you have an idea, how I can fix that?)?.

I don't think it matters too much while developing. We can fix the Git tree
after.

If you want to stay on top of master, then you should probably use git fetch, then git rebase master. Try to keep your commits in a single "thread". This often means you need to do a force push if you want to move your work on top of master - I'm perfectly fine with that.

The main drawback of "messy" commits is that I won't merge that "as is" - I might squash it or clean it up myself before merge. This might change the commit author metadata as a consequence. :\

Soo, to conclude: feel free to do as you want. As long as the suggested changes between the PR and the master branch reflect what you want, I'm happy.


In your last version, there seems to be a lot of new html files. Was that on purpose?

@TornaxO7
Copy link
Contributor Author

In your last version, there seems to be a lot of new html files. Was that on purpose?

No it wasn't. I thought that this directory came up, when I executed git fetch but after taking a look into this directory I think that I paste it from somewhere. I removed it now.

@TornaxO7
Copy link
Contributor Author

Ok, I've got a question about the vimtex/autoload/unite/sources: I saw that it's doing something with the table of contents. So if I've understood it right, vimtex/autoload/unite/sources/vimtex.vim has some functions, which are used to generate the TOC (if we use the :VimtexTocOpen command)?

@lervag
Copy link
Owner

lervag commented Feb 25, 2021

Ok, I've got a question about the vimtex/autoload/unite/sources: I saw that it's doing something with the table of contents. So if I've understood it right, vimtex/autoload/unite/sources/vimtex.vim has some functions, which are used to generate the TOC (if we use the :VimtexTocOpen command)?

This file is there to add the ToC unite source, see :help vimtex-unite (which is part of the vimtex-toc section). I don't think it needs much more explanation, except perhaps a like to the unite repo?

@TornaxO7
Copy link
Contributor Author

TornaxO7 commented Feb 25, 2021

Question [SOLVED]

What's the usage of autoad/vimtex/cache.vim?

@lervag
Copy link
Owner

lervag commented Feb 25, 2021

What's the usage of autoad/vimtex/cache.vim?

Well, caching..?

It defines a set of functions that make it quite easy to create and uses caches, both persistent and non-persistent caches. This is very useful to speed some types of things up, e.g. calls to kpsewhich.

@TornaxO7
Copy link
Contributor Author

TornaxO7 commented Feb 25, 2021

to create and uses caches, both persistent and non-persistent caches.

This information is what I needed! Thank you :)

Question [SOLVED]

What is the main usage for autoload/vimtex/delim.vim?

@lervag
Copy link
Owner

lervag commented Feb 28, 2021

This information is what I needed! Thank you :)

My pleasure :)

What is the main usage for autoload/vimtex/delim.vim?

A couple of things:

  1. It specifies an API for parsing various types of delimiters, as well as some "actions" on delimiters.

  2. The ...#init_buffer() function is called when a VimTeX buffer is loaded and defines e.g. the <plug>(vimtex-delim...) mappings that are mapped to functions. E.g. <plug>(vimtex-delim-toggle-modifier) which does ...#toggle_modifier. The <plug> mappings are given default "targets" in the function s:init_default_mappings in autoload/vimtex.vim, see e.g. here:

    vimtex/autoload/vimtex.vim

    Lines 141 to 147 in d99f8ff

    call s:map(1, 'n', 'dsd', '<plug>(vimtex-delim-delete)')
    call s:map(1, 'n', 'csd', '<plug>(vimtex-delim-change-math)')
    call s:map(1, 'n', 'tsd', '<plug>(vimtex-delim-toggle-modifier)')
    call s:map(1, 'x', 'tsd', '<plug>(vimtex-delim-toggle-modifier)')
    call s:map(1, 'n', 'tsD', '<plug>(vimtex-delim-toggle-modifier-reverse)')
    call s:map(1, 'x', 'tsD', '<plug>(vimtex-delim-toggle-modifier-reverse)')
    call s:map(1, 'i', ']]', '<plug>(vimtex-delim-close)')

Note that #init_buffer() is found in several files. See the function s:init_buffer in autoload/vimtex.vim: it loads the init_buffer() function in every file where it exists. This gives an interface to easily add new "modules" with new features to VimTeX.

@lervag
Copy link
Owner

lervag commented Mar 7, 2021

I realize this recent answer can be useful to you here as well: #1981 (comment)

@TornaxO7
Copy link
Contributor Author

TornaxO7 commented Mar 7, 2021

I don't really know where the latex directory came from. So I just removed it since it looks like that it was from me (sorry).

@TornaxO7
Copy link
Contributor Author

TornaxO7 commented Mar 7, 2021

Question [SOLVED]

I went through the debug.vim file. As far as I understood, it should create the stacktrace for the quickfix window. Now I'm unsure what kind of errors it uses. Does it fill the quickfix entries with the errors which come up from a LaTeX-Compiler or does it create the entries from vim itself? For example if you called an unknown function?

@lervag
Copy link
Owner

lervag commented Mar 7, 2021

I went through the debug.vim file. As far as I understood, it should create the stacktrace for the quickfix window.

Yes and no. It creates a stacktrace and allows to pass it to the quickfix window if there is an argument. That is, if you call it with any argument (regardless of how many and what they are), the stacktrace is inserted into the quickfix window. If not, then it only returns the stacktrace as a list.

Now I'm unsure what kind of errors it uses. Does it fill the quickfix entries with the errors which come up from a LaTeX-Compiler or does it create the entries from vim itself? For example if you called an unknown function?

This is internal debugging and is not related to LaTeX at all. What it does it that it parses the stacktrace from the v:throwpoint variable (see :h ...). If this does not exist, then we forcibly create it and remove the top element. It uses a couple of internal mechanisms to attempt to decipher the script local names (i.e. the s: in function! s:myfunc is appointed an internal number).

It should be quite easy to test it: just add call vimtex#debug#stacktrace(1) in some part of VimTeX that is loaded and see how it loads the trace into the quickfix list when you open a tex file.

@TornaxO7
Copy link
Contributor Author

It should be quite easy to test it: just add call vimtex#debug#stacktrace(1) in some part of VimTeX that is loaded and see how it loads the trace into the quickfix list when you open a tex file.

I'm getting this from the quickfix list:
GIF

Am I doing it correctly or why isn't there anything in the list?

@TornaxO7
Copy link
Contributor Author

TornaxO7 commented Mar 10, 2021

Question [SOLVED]

What is the purpose of vimtex/autoload/vimtex/context/cite.vim? vim-language-server can't find any references to the autoload-function vimtex#context#cite#new.

@lervag
Copy link
Owner

lervag commented Mar 10, 2021

Try this:

function! Test() abort
  try
    throw "oops"
  catch
    call vimtex#debug#stacktrace(1)
  endtry
endfunction

@TornaxO7
Copy link
Contributor Author

TornaxO7 commented Mar 10, 2021

Question [SOLVED]

What's the purpose of vimtex/autoload/vimtex/parser/vimcomplete.bst? It looks like a snippet file for me.

@lervag
Copy link
Owner

lervag commented Mar 10, 2021

What is the purpose of vimtex/autoload/vimtex/context/cite.vim? vim-language-server can't find any references to the autoload-function vimtex#context#cite#new.

It provides the citation context for the context menu, see vimtex/autoload/vimtex/context.vim. The latter automatically finds all context entries (currently, only cite.vim exists) and loads them.

See vimtex#contex#init_state. The s:handlers variable is defined at the script level and is a list of all files under context/*.vim, so you see the vimtex#context#{l:handler}#new() will be called with l:hander = 'cite'.

The same or a similar mechanism is used other places as well, e.g.

  • for the state initialization in vimtex#state#init() -> s:vimtex.new(...) with calls to vimtex#{l:mod}#init_state.
  • in vimtex#init() -> s:init_buffer() with the s:modules variable.

What's the purpose of vimtex/autoload/vimtex/parser/vimcomplete.bst? It looks like a snippet file for me.

It is used by parser/bib.vim in the s:parse_with_bibtex() function, which will actually run the bibtex problem with the supplied .bst file in order to convert a .bib file to a .bbl file that is much easier to parse.

- "Completed" the DOCUMENTATION.md file.
`vimtex/autoload/vimtex/parser/vimcomplete.bst`.
@TornaxO7
Copy link
Contributor Author

Ok so the DOCUMENTATION.md should be finished now. It should provide a rough overview of the plugin. You can start to review it now!

Copy link
Owner

@lervag lervag left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, I much appreciate this effort, and I agree this venture will become valuable. I have some comments, I hope you don't mind.

I also propose that I make a revision on top after we settle my comments. I want to clean up the language a little bit and perhaps add some more content/context where needed.

CONTRIBUTING.md Outdated
@@ -1,5 +1,17 @@
# Guide for code contributions

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can see the value of doctoc, but I don't expect this file to change that much, so I would propose to remove the auto update tags.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm... but I'd like to let

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
(...)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

there because, who know's how this file develops :)

CONTRIBUTING.md Outdated
VimTex provides a little high-level [documentation](./DOCUMENTATION.md). It's
still under development, but it might help you to understand the code better (or
at least faster). If you have any question about the code, feel free to open a
new issue!
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I propose to simplify this. Instead of a section, just add a short remark in the "Documentation style" section with a reference. Don't comment on the state of DOCUMENTATION.md, because it will change and we might forget to update this file.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

DOCUMENTATION.md Outdated
@@ -0,0 +1,235 @@
# Documentation

Welcome to the high-level documentation of **VimTex**.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if it is a good idea to highlight VimTeX (note capital X as in TeX). I don't do that in the README file either.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed :)

DOCUMENTATION.md Show resolved Hide resolved
DOCUMENTATION.md Show resolved Hide resolved
DOCUMENTATION.md Outdated
The `p` directory just includes more syntax highlighting rules which are *only*
loaded if they are needed.

### text_obj
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would use text_obj.vim as the title (and similar throughout) to make it clear that it is not a directory, but a file.

DOCUMENTATION.md Outdated
functions like `vimtex#text_obj#envtargets#current` to get the current
environment where the user is.

### view
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

view.vim vs the sub modules.

DOCUMENTATION.md Show resolved Hide resolved
DOCUMENTATION.md Outdated
The single file (`cite.vim`) is used for the `vimtex-context-citation` part.
[Here's](https://github.com/lervag/vimtex/pull/1961#issuecomment-795476750) a more detailed description of what it does and what's it's used for.

### fold
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As before: fold.vim > fold/*.vim

DOCUMENTATION.md Outdated

# test
This directory includes *all* test cases which have to pass in order to have a
stable and functional awesome VimTex plugin :) Each directory and filename
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hehe, thanks :)

But let's keep it simple and remove "awesome" and the similey. ;)

Copy link
Contributor Author

@TornaxO7 TornaxO7 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh damn. I didn't wanted to create a "review". I thought that I could response to you messages by clicking on this review button... sorry for doing this mess! ._. You can delete these comments starting from this one if you want (I can't delete them somehow).

CONTRIBUTING.md Outdated
@@ -1,5 +1,17 @@
# Guide for code contributions

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm... but I'd like to let

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
(...)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

there because, who know's how this file develops :)

CONTRIBUTING.md Outdated
VimTex provides a little high-level [documentation](./DOCUMENTATION.md). It's
still under development, but it might help you to understand the code better (or
at least faster). If you have any question about the code, feel free to open a
new issue!
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

DOCUMENTATION.md Outdated
@@ -0,0 +1,235 @@
# Documentation

Welcome to the high-level documentation of **VimTex**.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed :)

DOCUMENTATION.md Show resolved Hide resolved
DOCUMENTATION.md Show resolved Hide resolved
DOCUMENTATION.md Show resolved Hide resolved
DOCUMENTATION.md Outdated
Here's an example:
```vim
function VimTexCacheExample()
" create a new cache (if the name doesn't exist yet)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

DOCUMENTATION.md Show resolved Hide resolved
DOCUMENTATION.md Outdated
### debug.vim
This file is used for interal debugging and is not related to LaTeX at all. It
parses the stacktrace from the `v:throwpoint` variable (see `:h v:throwpoint`
for more information). If this does not exist, then we forcibly create
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Neo)Vim did that automatically for me. I fixed that now.

This directory includes all glyphs like α and β.

### context
The single file (`cite.vim`) is used for the `vimtex-context-citation` part.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm unsure what to write there instead. Could you do this for me or can you provide me some tipps?

@lervag
Copy link
Owner

lervag commented Mar 15, 2021

Oh damn. I didn't wanted to create a "review". I thought that I could response to you messages by clicking on this review button... sorry for doing this mess! ._. You can delete these comments starting from this one if you want (I can't delete them somehow).

No worries. I'll just respond inline here and look over the updates afterwards.

(Neo)Vim did that automatically for me. I fixed that now.

The context here is, I think, the indendation: I guess you have autoindent and smilar options enabled, perhaps even cindent.

I'm unsure what to write there instead. Could you do this for me or can you provide me some tipps?

Yes, no problem.

lervag added a commit that referenced this pull request Mar 15, 2021
@lervag
Copy link
Owner

lervag commented Mar 15, 2021

Thank you for this, I think it can bring a lot of value! I'll add some commits on top with some updates, and feel free to continue contributing if you have more ideas (either docs or other things)! :)

@lervag lervag closed this Mar 15, 2021
lervag added a commit that referenced this pull request Mar 15, 2021
@lervag
Copy link
Owner

lervag commented Mar 15, 2021

I've pushed a couple of additional commits on top of this now, and I think it has become quite good. Feel free to suggest more improvements.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants