-
Notifications
You must be signed in to change notification settings - Fork 391
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
Conversation
- Added Table of Contents in the CONTRIBUTE.md file - Added new section: 'Documentation' => Added a little file structure
CodequestionSo here comes the first question: In your EDIT |
- Started description of the vimtex#init() function.
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 |
Yes, that's sensible, thanks!
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
│ └── tex.vim | ||
├── test | ||
└── xclip | ||
``` |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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 ;)
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
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`) |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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). :)
- Added new file: DOCUMENTATION.md
Ok, I added the
The table of contents represents what I meant and you're right, I meant |
Oh no, I did |
I don't think it matters too much while developing. We can fix the Git tree If you want to stay on top of master, then you should probably use 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? |
No it wasn't. I thought that this directory came up, when I executed |
- after/ftplugin - autoload/health
Ok, I've got a question about the |
This file is there to add the ToC unite source, see |
Question [SOLVED]What's the usage of |
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 |
This information is what I needed! Thank you :) Question [SOLVED]What is the main usage for |
My pleasure :)
A couple of things:
Note that |
I realize this recent answer can be useful to you here as well: #1981 (comment) |
I don't really know where the |
Question [SOLVED]I went through the |
…sure what to add more.
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.
This is internal debugging and is not related to LaTeX at all. What it does it that it parses the stacktrace from the It should be quite easy to test it: just add |
Question [SOLVED]What is the purpose of |
Try this: function! Test() abort
try
throw "oops"
catch
call vimtex#debug#stacktrace(1)
endtry
endfunction |
Question [SOLVED]What's the purpose of |
It provides the citation context for the context menu, see See The same or a similar mechanism is used other places as well, e.g.
It is used by |
- "Completed" the DOCUMENTATION.md file.
`vimtex/autoload/vimtex/parser/vimcomplete.bst`.
Ok so the |
There was a problem hiding this 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 --> |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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! |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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**. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed :)
DOCUMENTATION.md
Outdated
The `p` directory just includes more syntax highlighting rules which are *only* | ||
loaded if they are needed. | ||
|
||
### text_obj |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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
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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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. ;)
…as a little remark in the `Documentation style` section. - Removed a little line of DOCTOC (https://github.com/thlorenz/doctoc)
- Set VimTeX style "bold" to "normal"
…rence to the "Learn Vimscript the Hard Way" book by Steve Losh.
Added a little hint to point out that VimTeX is using the `health.vim` framework for doing the health-checks.
- context.vim - fold.vim - text_obj.vim - view.vim TODO: - parser.vim - qf.vim
- parser.vim - qf.vim
There was a problem hiding this 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 --> |
There was a problem hiding this comment.
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! |
There was a problem hiding this comment.
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**. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed :)
DOCUMENTATION.md
Outdated
Here's an example: | ||
```vim | ||
function VimTexCacheExample() | ||
" create a new cache (if the name doesn't exist yet) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed
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 |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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?
No worries. I'll just respond inline here and look over the updates afterwards.
The context here is, I think, the indendation: I guess you have
Yes, no problem. |
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)! :) |
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. |
Currently added
=> 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?