207 lines
6.2 KiB
Plaintext
207 lines
6.2 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
|
|
@c %**start of header
|
|
@setfilename vscode-texinfo.info
|
|
@include version.texi
|
|
@settitle vscode-texinfo v@value{VERSION} User Manual
|
|
@c %**end of header
|
|
|
|
@copying
|
|
This manual is for vscode-texinfo, an extension of Visual Studio Code.
|
|
|
|
Copyright @copyright{} 2021 CismonX <admin@@cismon.net>
|
|
|
|
@quotation
|
|
Copying and distribution of this file, with or without modification, are
|
|
permitted in any medium without royalty, provided the copyright notice and
|
|
this notice are preserved. This file is offered as-is, without any warranty.
|
|
@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, an extension of Visual Studio Code.
|
|
|
|
Copyright @copyright{} 2021 CismonX <admin@@cismon.net>
|
|
|
|
Copying and distribution of this file, with or without modification, are
|
|
permitted in any medium without royalty, provided the copyright notice and
|
|
this notice are preserved. This file is offered as-is, without any warranty.
|
|
|
|
@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 source 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.
|
|
|
|
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 the 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.
|
|
|
|
|
|
@node Code Completion
|
|
@section Code Completion
|
|
|
|
|
|
@node Block Folding
|
|
@section Block Folding
|
|
|
|
|
|
@node Breadcrumb Navigation
|
|
@section Breadcrumb Navigation
|
|
|
|
|
|
@node Advanced Usage
|
|
@chapter Advanced Usage
|
|
|
|
|
|
@bye
|