329 lines
11 KiB
Plaintext
329 lines
11 KiB
Plaintext
\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 in regard to 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 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},
|
|
where contribution takes place. 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,
|
|
either @url{https://open-vsx.org/extension/CismonX/texinfo, Open VSX Registry},
|
|
or the proprietary Visual Studio Marketplace. Click the ``Extensions'' tab on
|
|
Visual Studio Code's sidebar, type ``texinfo'' and you can find and install this
|
|
extension.
|
|
|
|
You can also download the @code{.vsix} file, and manually install it to Visual
|
|
Studio Code (via command palette: @code{Extensions: Install from VSIX...}).
|
|
|
|
Before you manually 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
|
|
|
|
@menu
|
|
* Build from Source:: Build vscode-texinfo from source code.
|
|
@end menu
|
|
|
|
|
|
@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 the executable is 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, open a
|
|
Texinfo document, and look for a ``GNU Texinfo'' status bar item on the right
|
|
side of the status bar.
|
|
|
|
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.
|
|
|
|
@menu
|
|
* HTML Preview:: Display document preview in HTML format.
|
|
* Diagnosis:: Show diagnostic information.
|
|
@end menu
|
|
|
|
|
|
@node HTML Preview
|
|
@section HTML Preview
|
|
|
|
|
|
@node Diagnosis
|
|
@section Diagnosis
|
|
|
|
|
|
@bye
|