vscode-texinfo/doc/vscode-texinfo.texi

\input texinfo  @c -*-texinfo-*-

@c %**start of header
@setfilename vscode-texinfo.info
@include version.texi
@settitle User Manual for vscode-texinfo
@c %**end of header

@set vscode-docs-url https://code.visualstudio.com/docs

@copying
This manual is for vscode-texinfo (version @value{VERSION}), an extension of
Visual Studio Code.

Copyright @copyright{} 2021  CismonX <admin@@cismon.net>

@quotation
This manual is licensed under a
@url{https://creativecommons.org/licenses/by-sa/4.0/,
Creative Commons Attribution-ShareAlike 4.0 International License}.
@end quotation
@end copying

@titlepage
@title vscode-texinfo
@subtitle Texinfo Support for Visual Studio Code, version @value{VERSION}
@author CismonX

@page
@vskip 0pt plus 1filll
@insertcopying

@end titlepage


@summarycontents
@contents

@ifnottex
@node Top
@top vscode-texinfo

This manual is for vscode-texinfo (version @value{VERSION}), an extension of
Visual Studio Code.

Copyright @copyright{} 2021  CismonX <admin@@cismon.net>

This manual is licensed under a
@url{https://creativecommons.org/licenses/by-sa/4.0/,
Creative Commons Attribution-ShareAlike 4.0 International License}.

@end ifnottex


@menu
* Overview::        Brief overview of vscode-texinfo.
* Installation::    Install vscode-texinfo.
* Basic Usage::     Basic features of vscode-texinfo.
* Advanced Usage::  Advanced features of vscode-texinfo.
@end menu


@node Overview
@chapter Overview

Texinfo is a typesetting language designed for writing software manuals. It's
the official documention format for GNU projects, but not as popular in modern
non-GNU free software projects.

One of the main reasons is the lack of editor support. While Emacs does offer a
``texinfo-mode'', however, Emacs is not widely used among average software
developers.

We believe that Texinfo deserves more users, for it is an excellent format for
writing software manuals, as well as other technical materials. We chose Visual
Studio Code, one of the most popular code editors as of 2020, and developed this
very extension, vscode-texinfo, which provides some useful features for Visual
Studio Code regarding the Texinfo format, in the hope that more developers can
benefit from it.

vscode-texinfo is free software. You can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either @url{https://www.gnu.org/licenses/gpl-3.0-standalone.html,
version 3 of the License}, or (at your option) any later version.

@menu
* Contributing::  Contribute to vscode-texinfo.
@end menu


@node Contributing
@section Contributing

This project is hosted on @url{https://sv.gnu.org/p/vscode-texinfo, Savannah}.
Any kind of contribution is welcome, including bug reports, patches, and general
discussions regarding the usage of vscode-texinfo.

Before you submit something, please make sure that you have read this manual,
and no one else has posted the same content.


@node Installation
@chapter Installation

vscode-texinfo cannot be run standalone. It can only be used as an extension of
Visual Studio Code.

It is recommended to use a free distribution of Visual Studio Code,
@url{https://github.com/VSCodium/vscodium, VSCodium}, instead of the official
binary release, which is proprietary. You can also build it from
@url{https://github.com/microsoft/vscode, source} yourself.

@quotation Note
Theoretically vscode-texinfo can be installed on any version of Visual Studio
Code since 1.40, but not all versions are tested. It's recommended to install a
latest release.
@end quotation

The easiest way to install vscode-texinfo is from the extension marketplace.
Click the ``Extensions'' tab on Visual Studio Code's sidebar, type ``texinfo''
and you can find and install this extension.

@menu
* Manual Installation::  Download and install vscode-texinfo manually
* Build from Source::    Build vscode-texinfo from source code.
@end menu


@node Manual Installation
@section Manual Installation

You can manually download the @code{.vsix} file, from either Savannah's
@url{https://dl.sv.gnu.org/releases/vscode-texinfo/, download area},
@url{https://open-vsx.org/extension/CismonX/texinfo, Open VSX Registry}, or the
proprietary Visual Studio Marketplace.

Before you install a @code{.vsix} file downloaded from a third party,
you should check whether the file matches a trusted signature:

@example
wget -O cismonx.gpg.asc "https://sv.gnu.org/people/viewgpg.php?user_id=214244"
gpg --import cismonx.gpg.asc

wget https://dl.sv.gnu.org/releases/vscode-texinfo/texinfo-0.2.0.vsix.sig.asc
gpg --verify texinfo-0.2.0.vsix.sig.asc texinfo-0.2.0.vsix
@end example

Finally, install the @code{.vsix} file to Visual Studio Code via command
palette: @code{Extensions: Install from VSIX...}.


@node Build from Source
@section Build from Source

You can generate the @code{.vsix} file from the source code of vscode-texinfo.

First, clone the source code repository:

@example
git clone https://git.sv.gnu.org/git/vscode-texinfo.git
cd vscode-texinfo
@end example

Then, install dependencies via Node Package Manager, and build the project:

@example
npm ci
npm run package
@end example

If the operation is successful, a @code{texinfo-@{VERSION@}.vsix} file will be
generated under the root directory of the repository.


@node Basic Usage
@chapter Basic Usage

There are several basic features of vscode-texinfo which can be used
out-of-the-box.

@menu
* Syntax Highlighting::    Syntax highlighting for Texinfo documents.
* Code Completion::        Show completion list for @@-commands.
* Block Folding::          Collapse or expand code blocks.
* Breadcrumb Navigation::  Navigate between different contexts.
@end menu


@node Syntax Highlighting
@section Syntax Highlighting

The syntax highlighting solution is provided by
@url{https://github.com/Alhadis/language-texinfo, this TextMate Grammar}, which
is originally made for Atom, and also used in GitHub Linguist.

To enable Texinfo syntax highlighting when editing a file, it should be
recognized as a Texinfo document by Visual Studio Code. For file names with
suffix @code{.texi}, @code{.txi} or @code{.texinfo}, this process should be
automatic. If not, find and click the status bar item with ``Select Language
Mode'' tooltip, then choose ``Texinfo'' in the menu which just popped up.

If syntax highlighting does not look satisfactory, try another color theme where
keyword/operator colors are distinct. Some good examples are Solarized
Light/Dark, Monokai, etc.

For details about how to @url{@value{vscode-docs-url}
/languages/overview#_changing-the-language-for-the-selected-file,
change language mode} or @url{@value{vscode-docs-url}/getstarted/themes
#_selecting-the-color-theme, select color theme}, see the Visual Studio Code
User Guide.


@node Code Completion
@section Code Completion

When typing a @@-command in a Texinfo document, vscode-texinfo can display a
completion list so that you don't have to type the entire command.

There are two kinds of completion items: The command itself, and code snippets
related to that command.

A typical example of code snippet is the completion of a block command, say,
@code{@@example}. When applying completion, the generated code looks like:

@example
@@example

@@end example
@end example

The cursor falls between @code{@@example} and @code{@@end example}, where you
can finish the content of the @code{@@example} block. After that, press Tab to
bail out of the block.

Code snippet completion can be disabled by switching off the configuration item
@code{texinfo.completion.enableSnippets}.

When code snippet completion is enabled, completion of commands which relate to
code snippets is disabled by default. You can re-enable it on by switching off
@code{texinfo.completion.hideSnippetCommands}.

@quotation Note
Code completion provided by vscode-texinfo does not recognize much of Texinfo's
semantics, and completion may appear in contexts where it should not exist. This
is a known bug (which cannot be fixed in near future).
@end quotation


@node Block Folding
@section Block Folding

Block folding allows you to collapse a block of code in a Texinfo document, so
that you can navigate through the remaining part of the document more easily.

Three types of code blocks can be recognized by vscode-texinfo:

@itemize @bullet
@item Block commands
@item Chapters, sections and subsections
@item Consecutive lines of comments
@end itemize

While editing a Texinfo document, you can collape or expand a code block either
by clicking the folding icon to the left of the first line of the block, or by
invoking a corresponding command. See the Visual Studio Code User Guide for
@url{@value{vscode-docs-url}/editor/codebasics#_folding, details}.

@quotation Note
Due to performance issues, the block hierarchy of a Texinfo document is
re-calculated only when total line count changes, or when the document is saved.
@end quotation


@node Breadcrumb Navigation
@section Breadcrumb Navigation

Using the navigation bar, you can navigate through the code blocks defined in
@ref{Block Folding} (excluding blocks of comment lines). Titles of chapters and
sections are shown.

See the Visual Studio Code User Guide for more information about
@url{@value{vscode-docs-url}/editor/editingevolved#_breadcrumbs, Breadcrumbs}.


@node Advanced Usage
@chapter Advanced Usage

Some more advanced features of vscode-texinfo is available if GNU Texinfo is
correctly installed and configured on your device.

@url{https://www.gnu.org/software/texinfo, GNU Texinfo} is the official (and the
only known) full implementation of Texinfo. On most platforms, it can be easily
installed using a package manager. For example, if you're using a Debian-based
GNU/Linux distribution, you can install GNU Texinfo with:

@example
sudo apt-get install texinfo
@end example

GNU Texinfo provides a CLI program @code{makeinfo}, a.k.a. @code{texi2any},
which converts a Texinfo document to some other format, like HTML, PDF,
plain text, etc.

To specify the location of @code{makeinfo}, edit the configuration item
@code{texinfo.makeinfo}. If it's not located in @code{$PATH}, an absolute path
should be specified. Also note that the path should not contain any command line
arguments.

To check whether GNU Texinfo is correctly installed and configured, see
@ref{Version Indicator}.

@menu
* Version Indicator::  Show the installed version of GNU Texinfo
* HTML Preview::       Display document preview in HTML format.
* Diagnosis::          Show diagnostic information.
@end menu


@node Version Indicator
@section Version Indicator

The version indicator is as status bar item with text ``GNU Texinfo''. It is
located on the right side of the status bar, which is shown when the active text
editor contains a Texinfo document.

If you see a @b{check icon} and the version of GNU Texinfo, then
congratulations, you're all set. If a @b{cross icon} is displayed, it means
that GNU Texinfo is @emph{not} correctly installed and configured.

If a @b{warning icon} is displayed, it means that the currently installed GNU
Texinfo is outdated, or has an unrecognizable version number. In that case, some
features may not work as expected.

@quotation Note
The version indicator does not automatically refresh since the activation of the
extension. To manually trigger a refresh, click the status bar item.
@end quotation


@node HTML Preview
@section HTML Preview


@node Diagnosis
@section Diagnosis


@bye