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
@set vscode-api-url   https://code.visualstudio.com/api
@set gnu-texinfo-docs https://www.gnu.org/software/texinfo/manual/texinfo
@set sv-home-url      https://sv.nongnu.org
@set sv-releases-url  https://dl.sv.nongnu.org/releases

@tex
\global\def\linkcolor{0 0 1}
\global\def\urlcolor{0 0 1}
\global\urefurlonlylinktrue
@end tex

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

Copyright @copyright{} 2021,2024  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,2024  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 year 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{@value{sv-home-url}/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 post 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 software. You can also build it from
@url{https://github.com/microsoft/vscode, source} yourself.

@quotation Note
Theoretically vscode-texinfo can work with any version of Visual Studio Code
since 1.82, 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 (Extension ID:
@code{CismonX.texinfo}).

@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{@value{sv-releases-url}/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:

@set vsix-name texinfo-@value{VERSION}.vsix

@example
wget -O- '@value{sv-home-url}/people/viewgpg.php?user_id=214244' \
        | gpg --import
wget -O- @value{sv-releases-url}/vscode-texinfo/@value{vsix-name}.sig.asc \
        | gpg --verify - @value{vsix-name}
@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

The @code{.vsix} file can be built 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 with 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 source code 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, unless a
@url{https://microsoft.github.io/language-server-protocol/, language server}
for Texinfo is implemented, which is not trivial).
@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 collapse 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 a 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

You can generate the HTML preview of a Texinfo document in Visual Studio Code,
to see how the document looks like when displayed in a web browser.

In the active text editor which contains a Texinfo document, click the ``Show
Preview'' button on the top right of the editor. A webview will be created in a
split editor (if not already), and the HTML preview will be displayed there.
The ``Show Preview'' command is also available in command palette, and has a
default @code{Ctrl+K V} key binding (on GNU/Linux).

The HTML used for preview is generated by @code{makeinfo --html --nosplit}, and
Texinfo source is read from disk, instead of taken from a
@url{@value{vscode-api-url}/references/vscode-api#TextDocument,
@code{vscode.TextDocument}}. The editor may prompt you to save to file when
trying to display preview of a document which does not yet exist on disk, so
that the preview can be displayed.

An opened preview automatically tracks the behaviour of the corresponding
document. When the document is saved, the preview will refresh. When the editor
holding the document is closed, the preview also closes.

Texinfo documents tend to be rather large, and @code{makeinfo} may take some
time to finish. When you see an ``(Updating)'' in the title of a preview, it
means that the preview is being updated.

@menu
* Custom CSS::      Use custom stylesheets for HTML preview.
* Goto Node::       Jump to a node in preview.
* Misc Settings::   Miscellaneous configuration options regarding preview.
@end menu


@node Custom CSS
@subsection Custom CSS

You can use a custom CSS to make the HTML preview look prettier. To configure
this, edit the configuration option @code{texinfo.preview.customCSS}. The CSS
file can either be an online or a local (starting with @code{file://})
resource.

A good example is @url{https://www.gnu.org/software/gnulib/manual.css}, which
is popular among manuals of GNU projects. (Note: May require some tinkering
when used with darker editor themes)


@node Goto Node
@subsection Goto Node

Above each @code{@@node} line in a Texinfo document, a code lens with text
``Goto node in preview'' is shown. On click, it makes the HTML preview jump to
the corresponding location.

@quotation Note
@code{@@node} lines
@url{@value{gnu-texinfo-docs}/html_node/HTML-Xref-Command-Expansion.html,
allow @@-commands}, which is not handled in vscode-texinfo due to performance
considerations. For these nodes, this feature does not work.
@end quotation

To disable this feature and hide the code lenses, switch off the configuation
item @code{texinfo.enableCodeLens}.

See the Visual Studio Code User Guide for more information about
@url{@value{vscode-api-url}/references/vscode-api#CodeLens, CodeLens}.


@node Misc Settings
@subsection Misc Settings

There are some other settings which can affect the behaviour and appearance of
HTML previews.

@itemize @bullet
@item @code{texinfo.preview.errorLimit}: Number of errors which @code{makeinfo}
can produce before quitting. (@code{--error-limit=NUM})
@item @code{texinfo.preview.includePaths}: Array of extra paths to search for
@code{@@include} files. (@code{-I PATH})
@item @code{texinfo.preview.maxSize}: Max allowed size for the genereated HTML
file before it's displayed in the preview. Files larger than this limit will
trigger an error.
@item @code{texinfo.preview.noHeaders}: When enabled, headers and menus are no
longer displayed in preview. (@code{--no-headers})
@item @code{texinfo.preview.noNumberSections}: When enabled, do not display
chapter and section numbers in preview. (@code{--no-number-sections})
@item @code{texinfo.preview.noValidation}: When enabled, node cross-references
are not validated. (@code{--no-validate})
@item @code{texinfo.preview.variables}: Array of variables to define (as with
@code{@@set}). If a variable has a value, use the ASCII space character to
separate key and value.
@item @code{texinfo.preview.customizationVariables}: Array of customization
variables. (@code{-c KEY=VALUE})
@end itemize


@node Diagnosis
@section Diagnosis

Diagnosis can help you locate syntactic and semantic problems in a Texinfo
document, by parsing the error output of @code{makeinfo} and display the
diagnostic information on the editor.

The diagnostic information of a document is calculated automatically, whenever
an attempt to generate preview is made.

By default, all error and warning messages are shown. To disable warnings,
switch on the configuration item @code{texinfo.diagnosis.noWarnings}.


@bye