\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 @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 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