Latex-workshop: We should provide a user documentation

[jlelong]

The extension has grown up a lot over the last months with a lot new features, which is super great.

I think we should put some efforts to provide a documentation describing all this. In particular, a lot of configuration variables have been introduced to tweak the behavior of the extension and it is only a little described in package.json. This would also spare us a lot of false bug reports.

What is your feeling about it? Any idea, suggestion?

[James-Yu]

I absolutely agree with you. The readme was inherited from the ancient pre-1,0 time. How do you suggest we should rearrange it?

[tecosaur]

I'm totally onboard regarding a rewrite. Personally, I'd structure it by functionality/feature, as a generic user would probably only really look at it when changing something with regards to a specific feature.

Suggested Format

Some Feature

\

Usage

\

Related Settings

\

Example

ChkTeX

ChkTeX is a program installed in some LaTeX distributions that acts as a code linter for LaTeX code.

Usage

ChkTeX is automatically run on all LaTeX files when the feature is enabled. Potential issues will be reported as warnings.
\

Related Settings

| settings | description | default value | value type |
| --- | --- | --- | --- |
| latex-workshop.chktex.enabled | Turn ChkTeX on or off | false | boolean |
| latex-workshop.chktex.interval | How long before ChkTeX is invoked | 300 | (int) time in miliseconds |
| _etc._ | | | |

[jlelong]

A brief sketch of what I had in mind

Hosting the manual

We can create a GitHub Pages to have an online manual. The manual would be generated directly from .md files using Jekyll and we would have a fine control of the overall rendering. Several templates are already available. For instance, this is the approach used by vscode itself or Bootstrap.
@James-Yu as the owner of the project, you are the only who can create and configure a GitHub Page.

Content of the manual

Here is a proposal of a TOC

1. Installation and basic settings
2. Compiling
3. Viewing & synctex
4. Linters
5. Muti file projects
   
   
   
   • Auto detection of the "main" file.
   
   
   • Setting the main file manually
   
   
6. Intellisense
   
   
   
   • cite
   
   
   • label
   
   
   • filenames
   
   
7. Snippets and shortcuts
   
   
   
   • Inserting greek letters
   
   
   • Handy mathematical snippets
   
   
   • Font shorcuts
   
   
   • Some shortcuts coming from vim-latex
   
   
   • Surround text with a command
   
   
8. Playing with environments
   
   
   
   • Itemize: Enter to insert `\item``
   
   
   • Navigate between \begin and \end.
   
   
   • Close the current environment.
   
   
9. FAQ and common issues

Inside each item, we can use the format suggested by @tecosaur.

I will edit this post with the propositions from the coming discussion.

[James-Yu]

I will create a Page and see how it works. I'd like to re-write it soon, but I will have a IRL family vacation from the next week. Will see how I can contribute to the page.

[tecosaur]

To help with the workload i I'd be happy to write out the bits for the functionality I know about :)

Also that looks great jlelong!

[James-Yu]

The page is created and it seems that currently the README.md is parsed and converted. I also created a docs folder, but I'm not sure which source is better.

---

Maybe we can have a brief intro in the readme, which points the documentation to the page. How do you think?

[jlelong]

One thing to keep in mind: the Visual Studio Marketplace only displays the README. So to start, I would suggest to keep the README as it is and just add a link to the documentation.

The page is created and it seems that currently the README.md is parsed and converted. I also created a docs folder, but I'm not sure which source is better.

I cannot see the setting pane of the project but normally there is setting to set the source to build the Page and you have to choose master branch/docs. Once this is fixed, we have to choose a good theme for a documentation page. Something like the Just the docs theme would match our needs I guess. Any other suggestion is welcome. Then, I can make the setup and create the general structure and we will be ready to welcome contributions.

[tecosaur]

Sorry to add this a bit late, but have you considered a Github wiki? It seems like it would be perfect for this sort of thing.

[jlelong]

@tecosaur I had thought of it at the beginning but I had the feeling it was not really nice looking. Thanks to your comment, I have done a bit more googling and it seems more configurable than I thought, see here.
@James-Yu can you activate the wiki so that we can start playing a bit and see if it matches our needs?

[James-Yu]

No problem!

[jlelong]

I have started putting the general structure of the documentation based on my previous posts. Now, we have to fill the blanks.