2021-03-28 18:46:49 +00:00
|
|
|
\input texinfo @c -*-texinfo-*-
|
|
|
|
|
|
|
|
@c %**start of header
|
|
|
|
@setfilename vscode-texinfo.info
|
|
|
|
@include version.texi
|
2021-04-05 17:07:22 +00:00
|
|
|
@settitle User Manual for vscode-texinfo
|
2021-03-28 18:46:49 +00:00
|
|
|
@c %**end of header
|
|
|
|
|
2021-04-15 11:06:46 +00:00
|
|
|
@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
|
2021-04-01 10:41:56 +00:00
|
|
|
|
2021-05-04 19:43:37 +00:00
|
|
|
@tex
|
|
|
|
\global\def\linkcolor{0 0 1}
|
|
|
|
\global\def\urlcolor{0 0 1}
|
|
|
|
\global\urefurlonlylinktrue
|
|
|
|
@end tex
|
|
|
|
|
2021-03-28 18:46:49 +00:00
|
|
|
@copying
|
2021-04-06 12:30:20 +00:00
|
|
|
This manual is for vscode-texinfo (version @value{VERSION}), an extension of
|
|
|
|
Visual Studio Code.
|
2021-03-28 18:46:49 +00:00
|
|
|
|
|
|
|
Copyright @copyright{} 2021 CismonX <admin@@cismon.net>
|
|
|
|
|
|
|
|
@quotation
|
2021-04-06 12:30:20 +00:00
|
|
|
This manual is licensed under a
|
|
|
|
@url{https://creativecommons.org/licenses/by-sa/4.0/,
|
|
|
|
Creative Commons Attribution-ShareAlike 4.0 International License}.
|
2021-03-28 18:46:49 +00:00
|
|
|
@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
|
|
|
|
|
2021-04-05 17:07:22 +00:00
|
|
|
This manual is for vscode-texinfo (version @value{VERSION}), an extension of
|
|
|
|
Visual Studio Code.
|
2021-03-28 18:46:49 +00:00
|
|
|
|
|
|
|
Copyright @copyright{} 2021 CismonX <admin@@cismon.net>
|
|
|
|
|
2021-04-06 12:30:20 +00:00
|
|
|
This manual is licensed under a
|
|
|
|
@url{https://creativecommons.org/licenses/by-sa/4.0/,
|
|
|
|
Creative Commons Attribution-ShareAlike 4.0 International License}.
|
2021-03-28 18:46:49 +00:00
|
|
|
|
|
|
|
@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
|
|
|
|
|
2021-03-29 09:00:05 +00:00
|
|
|
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
|
2021-03-29 10:57:37 +00:00
|
|
|
writing software manuals, as well as other technical materials. We chose Visual
|
2021-05-25 09:00:27 +00:00
|
|
|
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.
|
2021-03-29 09:00:05 +00:00
|
|
|
|
|
|
|
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
|
2021-04-10 05:35:00 +00:00
|
|
|
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.
|
2021-03-29 09:00:05 +00:00
|
|
|
|
|
|
|
@menu
|
|
|
|
* Contributing:: Contribute to vscode-texinfo.
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
|
|
|
|
@node Contributing
|
|
|
|
@section Contributing
|
|
|
|
|
2021-04-10 05:35:00 +00:00
|
|
|
This project is hosted on @url{https://sv.gnu.org/p/vscode-texinfo, Savannah}.
|
2021-05-25 09:00:27 +00:00
|
|
|
Any kind of contribution is welcome, including bug reports, patches, and
|
|
|
|
general discussions regarding the usage of vscode-texinfo.
|
2021-03-29 09:00:05 +00:00
|
|
|
|
|
|
|
Before you submit something, please make sure that you have read this manual,
|
|
|
|
and no one else has posted the same content.
|
|
|
|
|
2021-03-28 18:46:49 +00:00
|
|
|
|
|
|
|
@node Installation
|
|
|
|
@chapter Installation
|
|
|
|
|
2021-03-29 09:00:05 +00:00
|
|
|
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
|
2021-05-04 19:43:37 +00:00
|
|
|
binary release, which is proprietary software. You can also build it from
|
2021-03-29 09:00:05 +00:00
|
|
|
@url{https://github.com/microsoft/vscode, source} yourself.
|
|
|
|
|
2021-04-02 11:54:51 +00:00
|
|
|
@quotation Note
|
2021-05-04 19:43:37 +00:00
|
|
|
Theoretically vscode-texinfo can work with any version of Visual Studio Code
|
|
|
|
since 1.40, but not all versions are tested. It's recommended to install a
|
|
|
|
latest release.
|
2021-04-02 11:54:51 +00:00
|
|
|
@end quotation
|
|
|
|
|
2021-04-10 05:35:00 +00:00
|
|
|
The easiest way to install vscode-texinfo is from the extension marketplace.
|
|
|
|
Click the ``Extensions'' tab on Visual Studio Code's sidebar, type ``texinfo''
|
2021-04-29 12:23:46 +00:00
|
|
|
and you can find and install this extension (Extension ID:
|
2021-05-04 19:43:37 +00:00
|
|
|
@code{CismonX.texinfo}).
|
2021-03-29 09:00:05 +00:00
|
|
|
|
2021-04-10 05:35:00 +00:00
|
|
|
@menu
|
2021-04-29 12:23:46 +00:00
|
|
|
* Manual Installation:: Download and install vscode-texinfo manually.
|
2021-04-10 05:35:00 +00:00
|
|
|
* 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.
|
2021-03-29 09:00:05 +00:00
|
|
|
|
2021-04-10 05:35:00 +00:00
|
|
|
Before you install a @code{.vsix} file downloaded from a third party,
|
2021-04-05 17:07:22 +00:00
|
|
|
you should check whether the file matches a trusted signature:
|
2021-03-29 09:00:05 +00:00
|
|
|
|
2021-05-25 09:00:27 +00:00
|
|
|
@set vsix-name texinfo-@value{VERSION}.vsix
|
|
|
|
|
2021-05-04 19:43:37 +00:00
|
|
|
@ifhtml
|
2021-03-29 09:00:05 +00:00
|
|
|
@example
|
|
|
|
wget -O cismonx.gpg.asc "https://sv.gnu.org/people/viewgpg.php?user_id=214244"
|
|
|
|
gpg --import cismonx.gpg.asc
|
|
|
|
|
2021-05-25 09:00:27 +00:00
|
|
|
wget https://dl.sv.gnu.org/releases/vscode-texinfo/@value{vsix-name}.sig.asc
|
|
|
|
gpg --verify @value{vsix-name}.sig.asc @value{vsix-name}
|
2021-03-29 09:00:05 +00:00
|
|
|
@end example
|
2021-05-04 19:43:37 +00:00
|
|
|
@end ifhtml
|
|
|
|
|
|
|
|
@ifnothtml
|
|
|
|
@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/
|
2021-05-25 09:00:27 +00:00
|
|
|
@value{vsix-name}.sig.asc"
|
|
|
|
gpg --verify @value{vsix-name}.sig.asc @value{vsix-name}
|
2021-05-04 19:43:37 +00:00
|
|
|
@end example
|
|
|
|
@end ifnothtml
|
|
|
|
|
2021-03-29 09:00:05 +00:00
|
|
|
|
2021-04-10 05:35:00 +00:00
|
|
|
Finally, install the @code{.vsix} file to Visual Studio Code via command
|
|
|
|
palette: @code{Extensions: Install from VSIX...}.
|
2021-03-29 10:57:37 +00:00
|
|
|
|
|
|
|
|
|
|
|
@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
|
|
|
|
|
2021-05-04 19:43:37 +00:00
|
|
|
Then, install dependencies with Node Package Manager, and build the project:
|
2021-03-29 10:57:37 +00:00
|
|
|
|
|
|
|
@example
|
|
|
|
npm ci
|
|
|
|
npm run package
|
|
|
|
@end example
|
|
|
|
|
2021-03-29 19:08:20 +00:00
|
|
|
If the operation is successful, a @code{texinfo-@{VERSION@}.vsix} file will be
|
2021-05-04 19:43:37 +00:00
|
|
|
generated under the root directory of the source code repository.
|
2021-03-29 10:57:37 +00:00
|
|
|
|
2021-03-28 18:46:49 +00:00
|
|
|
|
|
|
|
@node Basic Usage
|
|
|
|
@chapter Basic Usage
|
|
|
|
|
2021-03-29 19:08:20 +00:00
|
|
|
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.
|
|
|
|
|
2021-05-25 09:00:27 +00:00
|
|
|
If syntax highlighting does not look satisfactory, try another color theme
|
|
|
|
where keyword/operator colors are distinct. Some good examples are Solarized
|
2021-03-29 19:08:20 +00:00
|
|
|
Light/Dark, Monokai, etc.
|
|
|
|
|
2021-04-01 10:41:56 +00:00
|
|
|
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.
|
|
|
|
|
2021-03-29 19:08:20 +00:00
|
|
|
|
|
|
|
@node Code Completion
|
|
|
|
@section Code Completion
|
|
|
|
|
2021-03-30 12:26:48 +00:00
|
|
|
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,
|
2021-04-02 11:54:51 +00:00
|
|
|
@code{@@example}. When applying completion, the generated code looks like:
|
2021-03-30 12:26:48 +00:00
|
|
|
|
|
|
|
@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
|
2021-05-25 09:00:27 +00:00
|
|
|
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).
|
2021-03-30 12:26:48 +00:00
|
|
|
@end quotation
|
|
|
|
|
2021-03-29 19:08:20 +00:00
|
|
|
|
|
|
|
@node Block Folding
|
|
|
|
@section Block Folding
|
|
|
|
|
2021-03-31 12:51:29 +00:00
|
|
|
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
|
|
|
|
|
2021-05-25 09:00:27 +00:00
|
|
|
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}.
|
2021-03-31 12:51:29 +00:00
|
|
|
|
|
|
|
@quotation Note
|
|
|
|
Due to performance issues, the block hierarchy of a Texinfo document is
|
2021-05-25 09:00:27 +00:00
|
|
|
re-calculated only when total line count changes, or when the document is
|
|
|
|
saved.
|
2021-03-31 12:51:29 +00:00
|
|
|
@end quotation
|
|
|
|
|
2021-03-29 19:08:20 +00:00
|
|
|
|
|
|
|
@node Breadcrumb Navigation
|
|
|
|
@section Breadcrumb Navigation
|
|
|
|
|
2021-04-05 17:07:22 +00:00
|
|
|
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}.
|
|
|
|
|
2021-03-28 18:46:49 +00:00
|
|
|
|
|
|
|
@node Advanced Usage
|
|
|
|
@chapter Advanced Usage
|
|
|
|
|
2021-04-01 10:41:56 +00:00
|
|
|
Some more advanced features of vscode-texinfo is available if GNU Texinfo is
|
|
|
|
correctly installed and configured on your device.
|
|
|
|
|
2021-05-25 09:00:27 +00:00
|
|
|
@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:
|
2021-04-01 10:41:56 +00:00
|
|
|
|
|
|
|
@example
|
2021-04-05 17:07:22 +00:00
|
|
|
sudo apt-get install texinfo
|
2021-04-01 10:41:56 +00:00
|
|
|
@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
|
2021-04-10 05:35:00 +00:00
|
|
|
@code{texinfo.makeinfo}. If it's not located in @code{$PATH}, an absolute path
|
2021-05-25 09:00:27 +00:00
|
|
|
should be specified. Also note that the path should not contain any command
|
|
|
|
line arguments.
|
2021-04-01 10:41:56 +00:00
|
|
|
|
2021-04-10 05:35:00 +00:00
|
|
|
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
|
|
|
|
|
2021-05-04 19:43:37 +00:00
|
|
|
The version indicator is a status bar item with text ``GNU Texinfo''. It is
|
2021-05-25 09:00:27 +00:00
|
|
|
located on the right side of the status bar, which is shown when the active
|
|
|
|
text editor contains a Texinfo document.
|
2021-04-01 10:41:56 +00:00
|
|
|
|
2021-04-02 11:54:51 +00:00
|
|
|
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
|
2021-05-25 09:00:27 +00:00
|
|
|
Texinfo is outdated, or has an unrecognizable version number. In that case,
|
|
|
|
some features may not work as expected.
|
2021-04-01 10:41:56 +00:00
|
|
|
|
2021-04-10 05:35:00 +00:00
|
|
|
@quotation Note
|
2021-05-25 09:00:27 +00:00
|
|
|
The version indicator does not automatically refresh since the activation of
|
|
|
|
the extension. To manually trigger a refresh, click the status bar item.
|
2021-04-10 05:35:00 +00:00
|
|
|
@end quotation
|
2021-04-01 10:41:56 +00:00
|
|
|
|
|
|
|
|
|
|
|
@node HTML Preview
|
|
|
|
@section HTML Preview
|
|
|
|
|
2021-04-14 09:41:07 +00:00
|
|
|
You can generate the HTML preview of a Texinfo document in Visual Studio Code,
|
|
|
|
to see how the document looks like when displayed online.
|
|
|
|
|
|
|
|
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
|
2021-05-25 09:00:27 +00:00
|
|
|
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).
|
2021-04-14 09:41:07 +00:00
|
|
|
|
|
|
|
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
|
2021-04-15 11:06:46 +00:00
|
|
|
* Custom CSS:: Use custom stylesheets for HTML preview.
|
|
|
|
* Goto Node:: Jump to a node in preview.
|
|
|
|
* Misc Settings:: Miscellaneous configuration options regarding preview.
|
2021-04-14 09:41:07 +00:00
|
|
|
@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
|
2021-05-25 09:00:27 +00:00
|
|
|
file can either be an online or a local (starting with @code{file://})
|
|
|
|
resource.
|
2021-04-14 09:41:07 +00:00
|
|
|
|
2021-05-25 09:00:27 +00:00
|
|
|
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)
|
2021-04-14 09:41:07 +00:00
|
|
|
|
|
|
|
|
|
|
|
@node Goto Node
|
|
|
|
@subsection Goto Node
|
|
|
|
|
2021-04-15 11:06:46 +00:00
|
|
|
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
|
2021-04-22 12:37:01 +00:00
|
|
|
item @code{texinfo.enableCodeLens}.
|
2021-04-15 11:06:46 +00:00
|
|
|
|
|
|
|
See the Visual Studio Code User Guide for more information about
|
|
|
|
@url{@value{vscode-api-url}/references/vscode-api#CodeLens, CodeLens}.
|
|
|
|
|
|
|
|
|
2021-04-14 09:41:07 +00:00
|
|
|
@node Misc Settings
|
|
|
|
@subsection Misc Settings
|
|
|
|
|
2021-04-15 11:06:46 +00:00
|
|
|
There are some other settings which can affect the behaviour and appearance of
|
|
|
|
HTML previews.
|
|
|
|
|
|
|
|
@itemize @bullet
|
2021-04-29 12:23:46 +00:00
|
|
|
@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})
|
2021-04-15 11:06:46 +00:00
|
|
|
@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.
|
2021-04-29 12:23:46 +00:00
|
|
|
@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})
|
2021-04-15 11:06:46 +00:00
|
|
|
@item @code{texinfo.preview.noValidation}: When enabled, node cross-references
|
|
|
|
are not validated. (@code{--no-validate})
|
2021-04-29 12:23:46 +00:00
|
|
|
@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.
|
2021-04-15 11:06:46 +00:00
|
|
|
@end itemize
|
|
|
|
|
2021-04-01 10:41:56 +00:00
|
|
|
|
|
|
|
@node Diagnosis
|
|
|
|
@section Diagnosis
|
|
|
|
|
2021-04-29 12:23:46 +00:00
|
|
|
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}.
|
|
|
|
|
2021-03-28 18:46:49 +00:00
|
|
|
|
|
|
|
@bye
|