[texinfo/en] Learn Texinfo in Y minutes (#4263)

* [texinfo/en] Learn Texinfo in Y minutes

* Update texinfo.html.markdown

Co-authored-by: Andre Polykanine <ap@oire.me>

1 files changed, 183 insertions, 0 deletions

diff --git a/texinfo.html.markdown b/texinfo.html.markdown
new file mode 100644
index 00000000..c192e958
--- /dev/null
+++ b/texinfo.html.markdown
@@ -0,0 +1,183 @@
+---
+language: Texinfo
+contributors:
+    - ["Julien Lepiller", "https://github.com/roptat"]
+filename: learntexinfo.texi
+---
+
+Texinfo is a documentation format you can use to create various types of
+documents from the same source.  Its main usage is to create documentation
+manuals and info pages for GNU projects.
+
+Texinfo is a markup language that contains text and *@-commands* that specify
+what the generator should do.
+
+## Initial File
+
+A simple example of a simple manual:
+
+```texinfo
+\input texinfo
+@setfilename simple-document.info
+@documentencoding UTF-8
+@settitle simple-document
+@c This is a comment
+@c Replace simple-document above (twice) with the actual document title
+
+@c Automake will take care of version.texi
+@include version.texi
+
+@copying
+Copyright @copyright{} YEAR MY NAME
+
+@c GFDL is common for GNU projects
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
+@end quotation
+@end copying
+
+@titlepage
+@end titlepage
+
+@c Now starts the actual content
+@contents
+
+@c The first node must always be Top
+@node Top
+@c And we give it a title
+@top simple-document
+
+This document quickly describes Texinfo features.
+
+@c This is the ToC:
+@menu
+* Introduction::           A short summary of the chapter
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Introduction
+
+* Formatting::             How to format text nicely
+* Links::                  Linking to other resources, pages, or manuals
+
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+Each node must have the same name as the menu item that was defined in the ToC.
+
+@node Formatting
+@section Formatting
+@c Add something to the content index, so people can get here when searching
+@c for something else
+@cindex bold text
+@cindex titles
+
+Similar to chapters, sections must have the same name and appear in the same order.
+
+@subsection This is a subsection title
+@subsubsection This is a sub-subsection title
+
+Each block of text is a paragraph. You can use multiple lines for the paragraph
+like so, only empty lines separate paragraphs.
+
+Common formatting include @emph{emphasis}, @code{inline code}. Specific type of
+text can be marked as well: @file{file.txt}, @option{--learn-fast},
+@command{ls} or @var{variable}. You can escape the command character like
+so: @@, and a newline with a single @@ at the end of the line.
+
+You can add different types of blocks:
+
+@example
+Here is an example
+@end example
+
+@lisp
+'(this is lisp code)
+@end lisp
+
+@itemize
+@item An element in an unordered list
+@item A second element in the same list
+@end itemize
+
+@enumerate
+@item This list is similar
+@item But ordered
+@end enumerate
+
+@quotation
+A quotation block, by someone famous maybe
+@end quotation
+
+@table @asis
+@item element title
+element description
+
+@item second element title
+second element description. Note that the description part can span multiple
+paragraphs, contain other blocks etc. This is usually used as a definition
+list.
+
+@code{@@asis} wraps the element title, and tells Texinfo to use them as-is.
+@end table
+
+@table @code
+@item do-x
+This item title is now wrapped in a code block, as in @code{@@code{do-x}}
+@end table
+
+@c content index can appear at any place in the document, not necessarily after
+@c titles.
+@cindex function definition
+@deffn {Kind of Function} function_name @var{arg1} @var{arg2} @
+  @var{arg3} @var{arg4} [@var{optional5}]
+This text describes the function. Note how we could use multiple lines for the
+function synopsis by escaping the line with a single @@.
+
+This again can contain multiple paragraphs or blocks.
+@end deffn
+
+@node Links
+@section Links
+
+There are various types of links you can use. A simple link to a URL with
+@uref{https://github.com} and optionally with it a title:
+@uref{https://github.com, GitHub}. An email address @email{me@@me.me}.
+A node in this document, @xref{Introduction}. Always use the exact node name
+for that one. @code{xref} will include the text ``see'' before the link. To
+insert something different, use @pxref{Introduction} (``See'') or
+@xref{Introduction} (nothing is inserted). With an additional argument, you
+can change the text of the link, @xref{Introduction, this introduction}.
+
+It is possible to link to external manuals with these commands by adding
+more arguments, as in @code{@@xref{Node name,,, manual-name, link text}},
+@xref{Overview,,, texinfo, Texinfo's manual} for the complete reference
+on Texinfo!
+
+@bye
+```
+
+## How to Use It
+
+With `automake`, all you need to do is to give it the path to your manual
+in `Makefile.am`:
+
+```
+info_TEXINFOS= doc/simple-manual.texi
+```
+
+Then, get your info manual with `make doc/simple-manual.info` or in other formats,
+e.g. HTML with `make doc/simple-manual.html`.
+
+## Readings
+
+- [Official manual](https://www.gnu.org/software/texinfo/manual/texinfo/html_node/)