[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 3/3] Add Info mode manual
|
From: |
Antoine Kalmbach |
|
Subject: |
[PATCH 3/3] Add Info mode manual |
|
Date: |
Wed, 11 Nov 2020 11:35:28 +0200 |
* dir: generate with install-info --dir=dir rec-mode.info
* fdl.texi: move from recutils.git
* rec-mode.info: generate with makeinfo rec-mode.info
* rec-mode.texi: move from recutils.git
---
dir | 18 +
fdl.texi | 507 ++++++++++++++++++++++++++
rec-mode.info | 976 ++++++++++++++++++++++++++++++++++++++++++++++++++
rec-mode.texi | 469 ++++++++++++++++++++++++
4 files changed, 1970 insertions(+)
create mode 100644 dir
create mode 100644 fdl.texi
create mode 100644 rec-mode.info
create mode 100644 rec-mode.texi
diff --git a/dir b/dir
new file mode 100644
index 0000000..34b9d61
--- /dev/null
+++ b/dir
@@ -0,0 +1,18 @@
+This is the file .../info/dir, which contains the
+topmost node of the Info hierarchy, called (dir)Top.
+The first time you invoke Info you start off looking at this node.
+
+File: dir, Node: Top This is the top of the INFO tree
+
+ This (the Directory node) gives a menu of major topics.
+ Typing "q" exits, "H" lists all Info commands, "d" returns here,
+ "h" gives a primer for first-timers,
+ "mEmacs<Return>" visits the Emacs manual, etc.
+
+ In Emacs, you can click mouse button 2 on a menu item or cross reference
+ to select it.
+
+* Menu:
+
+Database
+* rec-mode: (rec-mode). Emacs mode for editing recfiles.
diff --git a/fdl.texi b/fdl.texi
new file mode 100644
index 0000000..08e7a99
--- /dev/null
+++ b/fdl.texi
@@ -0,0 +1,507 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008, 2020 Free Software
+Foundation, Inc.
+@uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, La@TeX{} input
+format, SGML or XML using a publicly available
+DTD, and standard-conforming simple HTML,
+PostScript or PDF designed for human modification. Examples
+of transparent image formats include PNG, XCF and
+JPG. Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, SGML or
+XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML,
+PostScript or PDF produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+@item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+@end enumerate
+
+@page
+@heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+ Copyright (C) @var{year} @var{your name}.
+ 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 group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.'' line with this:
+
+@smallexample
+@group
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
+
diff --git a/rec-mode.info b/rec-mode.info
new file mode 100644
index 0000000..4c8e042
--- /dev/null
+++ b/rec-mode.info
@@ -0,0 +1,976 @@
+This is rec-mode.info, produced by makeinfo version 6.7 from
+rec-mode.texi.
+
+This manual is for rec-mode for Emacs, which is part of the GNU recutils
+suite (version 1.8.90, 7 November 2020).
+
+ Copyright (C) 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020
+Jose E. Marchesi
+
+ 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".
+INFO-DIR-SECTION Database
+START-INFO-DIR-ENTRY
+* rec-mode: (rec-mode). Emacs mode for editing recfiles.
+END-INFO-DIR-ENTRY
+
+
+File: rec-mode.info, Node: Top, Next: Introduction, Up: (dir)
+
+rec-mode: an Emacs mode for editing recfiles
+********************************************
+
+This manual documents version 1.8.90 of rec-mode.
+
+ This manual is for rec-mode for Emacs, which is part of the GNU
+recutils suite (version 1.8.90, 7 November 2020).
+
+ Copyright (C) 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020
+Jose E. Marchesi
+
+ 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".
+
+* Menu:
+
+* Introduction:: Getting started
+* Navigation mode:: User-friendly interface for browing recfiles
+* Edition modes:: Edit recfiles in rec-format
+* Configuration:: Adapting rec-mode to your needs
+* GNU Free Documentation License:: Distribution terms for this document
+
+ -- The Detailed Node Listing --
+
+Introduction
+
+* Installation:: How to install rec-mode
+* Activation:: How to activate rec-mode for certain buffers
+* Feedback:: Bug reports, ideas, patches etc.
+
+Navigation mode
+
+* Record navigation:: Moving through records.
+* Field navigation:: Moving through fields in a record.
+* Field folding:: Hiding and showing the values of fields.
+* Field edition:: Changing the values of fields.
+* Searches:: Finding records fufilling some criteria.
+* Statistics:: Counting records.
+* Data integrity:: Verifying the integrity of the recfile.
+
+Edition modes
+
+* Edition modes:: Edit recfiles in rec-format
+
+Configuration
+
+* Finding the recutils:: Specifying the location of the recutils.
+* Records appearance:: Setting the way records are displayed.
+
+
+File: rec-mode.info, Node: Introduction, Next: Navigation mode, Prev: Top,
Up: Top
+
+1 Introduction
+**************
+
+rec-mode is a mode for browsing and editing recfiles, which are text
+files containing data structured in fields and records. It is part of
+the GNU recutils(1) suite.
+
+ Recfiles are text-based databases which are easy to read and write
+manually using a text editor. At the same time they feature enough
+structure so they can be read, edited and processed automatically by
+programs.
+
+* Menu:
+
+* Installation:: How to install rec-mode
+* Activation:: How to activate rec-mode for certain buffers
+* Feedback:: Bug reports, ideas, patches etc.
+
+ ---------- Footnotes ----------
+
+ (1) <http://www.gnu.org/software/recutils>
+
+
+File: rec-mode.info, Node: Installation, Next: Activation, Up: Introduction
+
+1.1 Installation
+================
+
+rec-mode is implemented in a self-contained elisp file called
+'rec-mode.el'. It can be obtained in several ways:
+
+ - As part of a released tarball of recutils. 'rec-mode.el' can be
+ found in the 'etc/' directory in the tarball contents.
+ - As part of the source tree cloned from the development git repo.
+ 'rec-mode.el' can be found in the 'etc/' directory in the recutils
+ sources tree.
+ - As a single file downloaded form some other location in internet.
+ - It may be already installed as part of a binary package in some
+ distribution.
+
+In the first three cases you need to tell Emacs where to locate the
+'rec-mode.el' file and to load it. Add the following to your '.emacs'
+file.
+ (add-to-list 'load-path "~/path/to/recmode/")
+ (require 'rec-mode)
+
+If 'rec-mode.el' was installed as part of a binary package in a
+distribution then you usually don't have to touch the 'load-path'
+variable. Depending on the specific case you may have to 'require' the
+package.
+
+
+File: rec-mode.info, Node: Activation, Next: Feedback, Prev: Installation,
Up: Introduction
+
+1.2 Activation
+==============
+
+To make sure files with extension '.rec' use rec-mode, add the following
+line to your '.emacs' file.
+ (add-to-list 'auto-mode-alist '("\\.rec\\'" . rec-mode))
+rec-mode buffers need font-lock to be turned on - this is the default in
+Emacs(1).
+
+ With this setup, all files with extension '.rec' will be put into rec
+mode. As an alternative, make the first line of a recfile look like
+this:
+
+ # -*- mode: rec -*-
+
+which will select rec-mode for this buffer no matter what the file's
+name is.
+
+ ---------- Footnotes ----------
+
+ (1) If you don't use font-lock globally, turn it on in the rec buffer
+with '(add-hook 'rec-mode-hook 'turn-on-font-lock)'
+
+
+File: rec-mode.info, Node: Feedback, Prev: Activation, Up: Introduction
+
+1.3 Feedback
+============
+
+If you find problems with rec-mode, or if you have questions, remarks,
+or ideas about it, please mail to the recutils mailing list
+<bug-recutils@gnu.org>. If you are not a member of the mailing list,
+your mail will be passed to the list after a moderator has approved
+it(1).
+
+ ---------- Footnotes ----------
+
+ (1) Please consider subscribing to the mailing list, in order to
+minimize the work the mailing list moderators have to do. The
+subscription can be done online at
+<http://lists.gnu.org/mailman/listinfo/bug-recutils>.
+
+
+File: rec-mode.info, Node: Navigation mode, Next: Edition modes, Prev:
Introduction, Up: Top
+
+2 Navigation mode
+*****************
+
+When a recfile is visited in Emacs and rec-mode is activated, the
+contents of the file are examined and parsed in order to determine if it
+is a valid recfile and, in that case, to extract information like the
+kind of records stored in the file.
+
+ If the file does not contain valid rec data then the buffer is put in
+'fundamental-mode' and a description of the syntax error, along its
+location, is notified in the echo area.
+
+ If the file contains valid rec data, the mode sets itself in what is
+known as "navigation mode". In this mode the buffer is made read-only
+and it is narrowed to the first record present in the file. Also, the
+presentation of the record contents is slightly changed in order to
+improve the visualization of the data: continuation line marks are
+replaced by indentation, big fields are folded, etc. The modeline is
+changed in order to reflect the type of the records being navigated.
+
+ At this point the user can navigate through the records and fields
+contained in the file, and edit the contents of the fields and the
+structure of the records, by using the commands described in the
+following subsections.
+
+* Menu:
+
+* Record navigation:: Moving through records
+* Field navigation:: Moving through fields in a record
+* Field folding:: Hiding and showing the values of fields
+* Field edition:: Changing the values of fields
+* Searches:: Finding records fulfilling some criteria
+* Statistics:: Counting records
+* Data integrity:: Verifying the integrity of the recfile
+
+
+File: rec-mode.info, Node: Record navigation, Next: Field navigation, Up:
Navigation mode
+
+2.1 Record navigation
+=====================
+
+The following commands jump to other records in the buffer.
+
+'n' ('rec-cmd-goto-next-rec')
+ Display the next record of the same type in the buffer.
+ 'C-u N n' will move next N times.
+'p' ('rec-cmd-goto-previous-rec')
+ Display the previous record of the same type in the buffer.
+ 'C-u N p' will move backwards N times.
+'d' ('rec-cmd-show-descriptor')
+ Display the record descriptor applicable to the current record. If
+ the current record is anonymous, i.e. there is not record
+ descriptor. then this command does nothing.
+'b' ('rec-cmd-jump-back')
+ Display the record previously displayed in the buffer.
+'C-c t' ('rec-find-type')
+ Prompt the user for one of the record types present in the recfile
+ and display the first record of the selected type.
+
+
+File: rec-mode.info, Node: Field navigation, Next: Field folding, Prev:
Record navigation, Up: Navigation mode
+
+2.2 Field navigation
+====================
+
+The following commands iterate through the fields in a record, and to
+get information about some of the properties of the fields.
+
+'TAB' ('rec-cmd-goto-next-field')
+ Move the cursor to the beginning of the name of the next field in
+ the current record. If the cursor is currently located at the last
+ field of the record then move it to the beginning of the first
+ field.
+'t' ('rec-cmd-show-type')
+ Show information about the type of the field under the cursor, if
+ it is defined.
+
+
+File: rec-mode.info, Node: Field folding, Next: Field edition, Prev: Field
navigation, Up: Navigation mode
+
+2.3 Field folding
+=================
+
+Fields in recfiles can contain data of any size, and sometimes it is
+difficult to have an overview of the contents of the record. The
+following commands fold and unfold the value of the field under the
+cursor.
+
+'SPC' ('rec-cmd-toggle-field-visibility')
+ Toggle the visibility of the field under the cursor. When a field
+ is folded then three dots are displayed in the buffer instead of
+ the value of the field.
+
+ It is possible to automatically fold any field whose value exceeds
+ a certain limit which can be configured by the user. *Note Records
+ appearance::.
+
+
+File: rec-mode.info, Node: Field edition, Next: Searches, Prev: Field
folding, Up: Navigation mode
+
+2.4 Field edition
+=================
+
+The following commands change the value of the field under the cursor.
+
+'e' ('rec-cmd-edit-field')
+ Edit the value of the field under the cursor. The specific action
+ depends on the type of the field in the corresponding record
+ descriptor:
+ - For date fields a calendar buffer is opened in another window
+ and the focus is moved there. The user can then select a date
+ by moving the cursor there and press 'RET' in order to set
+ that date as the value for the field. Alternatively the user
+ can press 't' in order to set the field to "now", or 'q' to
+ cancel the operation. In the later case the value of the
+ field is left untouched.
+ - For enumerated and bool fields a fast-select buffer is opened
+ in another window, showing a list of labeled options. The
+ labels are single digits and letters. The user can then
+ select ony of the options by pressing the corresponding label,
+ or cancel the operation by pressing 'RET'. In the later case
+ the value of the field is left untouched.
+ - For any other kind of fields an edition buffer is opened in
+ another window, showing the current contents of the field.
+ The user can then edit the buffer as desired. When she is
+ done, the user can then press 'C-c C-c' in order to set the
+ new value of the field, or just kill the buffer to cancel the
+ operation.
+'m' ('rec-cmd-trim-field-value')
+ Trim the value of the field under the cursor, removing any sequence
+ of leading and trailing blank characters.
+
+
+File: rec-mode.info, Node: Searches, Next: Statistics, Prev: Field edition,
Up: Navigation mode
+
+2.5 Searches
+============
+
+The following commands jump to the first record in the buffer satisfying
+some criteria.
+
+'s q' ('rec-cmd-select-fast')
+ Display the first record having a field whose value matches a given
+ fixed pattern. This is equivalent of using the command line option
+ '-q' of 'recsel'. If a prefix argument is specified then the
+ search is case-insensitive.
+'s s' ('rec-cmd-select-sex')
+ Display the first record in the buffer satisfying a given selection
+ expression. This is equivalent of using the command line option
+ '-e' of 'recsel'. If a prefix argument is specified then the
+ search is case-insensitive.
+
+
+File: rec-mode.info, Node: Statistics, Next: Data integrity, Prev:
Searches, Up: Navigation mode
+
+2.6 Statistics
+==============
+
+The following commands allow to count records in the current buffer
+based on some provided criteria.
+
+'I' ('rec-cmd-show-info')
+ Show the number of records in the buffer categorized by type.
+'#' ('rec-cmd-count')
+ Count the number of records in the buffer having the same type as
+ the current record. With a numeric prefix N, ask for a selection
+ expression and count the number of records in the buffer satisfying
+ the expression.
+
+ Note that rec-mode tries to guess a reasonable default for the
+ selection expression, depending on the type of the field and its
+ value. If the user press 'RET' then the provided default selection
+ expression is used.
+'%' ('rec-cmd-statistics')
+ If the field under the cursor contains an enumerated value, show
+ the percentages of records in the current record set having fields
+ with each of the possible values of the enumerated type.
+
+
+File: rec-mode.info, Node: Data integrity, Prev: Statistics, Up: Navigation
mode
+
+2.7 Data integrity
+==================
+
+The integrity of the rec data stored in the file can be checked using
+the following commands.
+
+'c' ('rec-cmd-compile')
+ Compile the buffer with 'recfix' and open a compilation window
+ showing the result of the command. In case some error or warning
+ is reported, the user can jump to the location triggering the error
+ by pressing 'RET' in the compilation window.
+
+
+File: rec-mode.info, Node: Edition modes, Next: Configuration, Prev:
Navigation mode, Up: Top
+
+3 Edition modes
+***************
+
+The navigation mode described in a previous chapter is mainly intended
+for browsing recdata and doing changes at the record level: editing the
+contents of a field, adding or removing fields, etc. In order to
+perform broader changes, such as adding/deleting record descriptors,
+records or comment blocks, the user must enter into one of the "edition
+modes".
+
+ There are three edition modes, covering different areas of the
+recfile: record, record type and buffer. When an edition mode is
+entered the buffer is set in read/write mode, it is narrowed to the
+desired area and any embellishment used in navigation mode is
+removed(1). As a general rule, the commands available in navigation
+mode are also available in the edition mode prefixed with 'C-c'. Thus,
+'C-c n' would make the cursor to jump to the beginning of the next
+record.
+
+ The following commands are used to enter into one of the available
+edition modes from the navigation mode.
+
+'R' ('rec-edit-record')
+ Edit the record being navigated.
+'T' ('rec-edit-type')
+ Edit the record set being navigated.
+'B' ('rec-edit-buffer')
+ Edit the buffer.
+
+After doing modifications in the buffer, the user can go back to
+navigation mode by using the following command.
+
+'C-c C-c' ('rec-finish-editing')
+ Finish the current edition and return to navigation mode. If a
+ syntactic error was introduced in the edition activity then the
+ error is reported in the echo area and navigation mode is not
+ entered.
+
+ ---------- Footnotes ----------
+
+ (1) Exceptuating font-lock
+
+
+File: rec-mode.info, Node: Configuration, Next: GNU Free Documentation
License, Prev: Edition modes, Up: Top
+
+4 Configuration
+***************
+
+TBC
+
+* Menu:
+
+* Finding the recutils:: Specifying the location of the recutils.
+* Records appearance:: Setting the way records are displayed
+
+
+File: rec-mode.info, Node: Finding the recutils, Next: Records appearance,
Up: Configuration
+
+4.1 Finding the recutils
+========================
+
+'rec-mode' makes use of the several utilities which are part of the
+recutils. The following variables tell the mode where to find the
+utilities. The default values of these variables must work if the
+recutils are installed system-wide in the system.
+
+'rec-recsel'
+ Name of the 'recsel' utility from the GNU recutils.
+'rec-recinf'
+ Name of the 'recinf' utility from the GNU recutils.
+'rec-recfix'
+ Name of the 'recfix' utility from the GNU recutils.
+
+
+File: rec-mode.info, Node: Records appearance, Prev: Finding the recutils,
Up: Configuration
+
+4.2 Records appearance
+======================
+
+The appearance of the records in navigation mode can be customised by
+tweaking the value of the following variables.
+
+'rec-max-lines-in-fields'
+ Values in fiels having more than the specified number of lines will
+ be hidden by default in navigation mode. When hidden, an ellipsis
+ is shown instead of the value of the field. Default is '15'.
+
+
+File: rec-mode.info, Node: GNU Free Documentation License, Prev:
Configuration, Up: Top
+
+Appendix A GNU Free Documentation License
+*****************************************
+
+ Version 1.3, 3 November 2008
+
+ Copyright (C) 2000, 2001, 2002, 2007, 2008, 2020 Free Software
+ Foundation, Inc.
+ <http://fsf.org/>
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ 0. PREAMBLE
+
+ The purpose of this License is to make a manual, textbook, or other
+ functional and useful document "free" in the sense of freedom: to
+ assure everyone the effective freedom to copy and redistribute it,
+ with or without modifying it, either commercially or
+ noncommercially. Secondarily, this License preserves for the
+ author and publisher a way to get credit for their work, while not
+ being considered responsible for modifications made by others.
+
+ This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense.
+ It complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same freedoms
+ that the software does. But this License is not limited to
+ software manuals; it can be used for any textual work, regardless
+ of subject matter or whether it is published as a printed book. We
+ recommend this License principally for works whose purpose is
+ instruction or reference.
+
+ 1. APPLICABILITY AND DEFINITIONS
+
+ This License applies to any manual or other work, in any medium,
+ that contains a notice placed by the copyright holder saying it can
+ be distributed under the terms of this License. Such a notice
+ grants a world-wide, royalty-free license, unlimited in duration,
+ to use that work under the conditions stated herein. The
+ "Document", below, refers to any such manual or work. Any member
+ of the public is a licensee, and is addressed as "you". You accept
+ the license if you copy, modify or distribute the work in a way
+ requiring permission under copyright law.
+
+ A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+
+ A "Secondary Section" is a named appendix or a front-matter section
+ of the Document that deals exclusively with the relationship of the
+ publishers or authors of the Document to the Document's overall
+ subject (or to related matters) and contains nothing that could
+ fall directly within that overall subject. (Thus, if the Document
+ is in part a textbook of mathematics, a Secondary Section may not
+ explain any mathematics.) The relationship could be a matter of
+ historical connection with the subject or with related matters, or
+ of legal, commercial, philosophical, ethical or political position
+ regarding them.
+
+ The "Invariant Sections" are certain Secondary Sections whose
+ titles are designated, as being those of Invariant Sections, in the
+ notice that says that the Document is released under this License.
+ If a section does not fit the above definition of Secondary then it
+ is not allowed to be designated as Invariant. The Document may
+ contain zero Invariant Sections. If the Document does not identify
+ any Invariant Sections then there are none.
+
+ The "Cover Texts" are certain short passages of text that are
+ listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+ that says that the Document is released under this License. A
+ Front-Cover Text may be at most 5 words, and a Back-Cover Text may
+ be at most 25 words.
+
+ A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, that is suitable for revising the document
+ straightforwardly with generic text editors or (for images composed
+ of pixels) generic paint programs or (for drawings) some widely
+ available drawing editor, and that is suitable for input to text
+ formatters or for automatic translation to a variety of formats
+ suitable for input to text formatters. A copy made in an otherwise
+ Transparent file format whose markup, or absence of markup, has
+ been arranged to thwart or discourage subsequent modification by
+ readers is not Transparent. An image format is not Transparent if
+ used for any substantial amount of text. A copy that is not
+ "Transparent" is called "Opaque".
+
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format,
+ SGML or XML using a publicly available DTD, and standard-conforming
+ simple HTML, PostScript or PDF designed for human modification.
+ Examples of transparent image formats include PNG, XCF and JPG.
+ Opaque formats include proprietary formats that can be read and
+ edited only by proprietary word processors, SGML or XML for which
+ the DTD and/or processing tools are not generally available, and
+ the machine-generated HTML, PostScript or PDF produced by some word
+ processors for output purposes only.
+
+ The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the
+ material this License requires to appear in the title page. For
+ works in formats which do not have any title page as such, "Title
+ Page" means the text near the most prominent appearance of the
+ work's title, preceding the beginning of the body of the text.
+
+ The "publisher" means any person or entity that distributes copies
+ of the Document to the public.
+
+ A section "Entitled XYZ" means a named subunit of the Document
+ whose title either is precisely XYZ or contains XYZ in parentheses
+ following text that translates XYZ in another language. (Here XYZ
+ stands for a specific section name mentioned below, such as
+ "Acknowledgements", "Dedications", "Endorsements", or "History".)
+ To "Preserve the Title" of such a section when you modify the
+ Document means that it remains a section "Entitled XYZ" according
+ to this definition.
+
+ The Document may include Warranty Disclaimers next to the notice
+ which states that this License applies to the Document. These
+ Warranty Disclaimers are considered to be included by reference in
+ this License, but only as regards disclaiming warranties: any other
+ implication that these Warranty Disclaimers may have is void and
+ has no effect on the meaning of this License.
+
+ 2. VERBATIM COPYING
+
+ You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License
+ applies to the Document are reproduced in all copies, and that you
+ add no other conditions whatsoever to those of this License. You
+ may not use technical measures to obstruct or control the reading
+ or further copying of the copies you make or distribute. However,
+ you may accept compensation in exchange for copies. If you
+ distribute a large enough number of copies you must also follow the
+ conditions in section 3.
+
+ You may also lend copies, under the same conditions stated above,
+ and you may publicly display copies.
+
+ 3. COPYING IN QUANTITY
+
+ If you publish printed copies (or copies in media that commonly
+ have printed covers) of the Document, numbering more than 100, and
+ the Document's license notice requires Cover Texts, you must
+ enclose the copies in covers that carry, clearly and legibly, all
+ these Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also clearly
+ and legibly identify you as the publisher of these copies. The
+ front cover must present the full title with all words of the title
+ equally prominent and visible. You may add other material on the
+ covers in addition. Copying with changes limited to the covers, as
+ long as they preserve the title of the Document and satisfy these
+ conditions, can be treated as verbatim copying in other respects.
+
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto
+ adjacent pages.
+
+ If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a machine-readable
+ Transparent copy along with each Opaque copy, or state in or with
+ each Opaque copy a computer-network location from which the general
+ network-using public has access to download using public-standard
+ network protocols a complete Transparent copy of the Document, free
+ of added material. If you use the latter option, you must take
+ reasonably prudent steps, when you begin distribution of Opaque
+ copies in quantity, to ensure that this Transparent copy will
+ remain thus accessible at the stated location until at least one
+ year after the last time you distribute an Opaque copy (directly or
+ through your agents or retailers) of that edition to the public.
+
+ It is requested, but not required, that you contact the authors of
+ the Document well before redistributing any large number of copies,
+ to give them a chance to provide you with an updated version of the
+ Document.
+
+ 4. MODIFICATIONS
+
+ You may copy and distribute a Modified Version of the Document
+ under the conditions of sections 2 and 3 above, provided that you
+ release the Modified Version under precisely this License, with the
+ Modified Version filling the role of the Document, thus licensing
+ distribution and modification of the Modified Version to whoever
+ possesses a copy of it. In addition, you must do these things in
+ the Modified Version:
+
+ A. Use in the Title Page (and on the covers, if any) a title
+ distinct from that of the Document, and from those of previous
+ versions (which should, if there were any, be listed in the
+ History section of the Document). You may use the same title
+ as a previous version if the original publisher of that
+ version gives permission.
+
+ B. List on the Title Page, as authors, one or more persons or
+ entities responsible for authorship of the modifications in
+ the Modified Version, together with at least five of the
+ principal authors of the Document (all of its principal
+ authors, if it has fewer than five), unless they release you
+ from this requirement.
+
+ C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+ D. Preserve all the copyright notices of the Document.
+
+ E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+ F. Include, immediately after the copyright notices, a license
+ notice giving the public permission to use the Modified
+ Version under the terms of this License, in the form shown in
+ the Addendum below.
+
+ G. Preserve in that license notice the full lists of Invariant
+ Sections and required Cover Texts given in the Document's
+ license notice.
+
+ H. Include an unaltered copy of this License.
+
+ I. Preserve the section Entitled "History", Preserve its Title,
+ and add to it an item stating at least the title, year, new
+ authors, and publisher of the Modified Version as given on the
+ Title Page. If there is no section Entitled "History" in the
+ Document, create one stating the title, year, authors, and
+ publisher of the Document as given on its Title Page, then add
+ an item describing the Modified Version as stated in the
+ previous sentence.
+
+ J. Preserve the network location, if any, given in the Document
+ for public access to a Transparent copy of the Document, and
+ likewise the network locations given in the Document for
+ previous versions it was based on. These may be placed in the
+ "History" section. You may omit a network location for a work
+ that was published at least four years before the Document
+ itself, or if the original publisher of the version it refers
+ to gives permission.
+
+ K. For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section
+ all the substance and tone of each of the contributor
+ acknowledgements and/or dedications given therein.
+
+ L. Preserve all the Invariant Sections of the Document, unaltered
+ in their text and in their titles. Section numbers or the
+ equivalent are not considered part of the section titles.
+
+ M. Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+ N. Do not retitle any existing section to be Entitled
+ "Endorsements" or to conflict in title with any Invariant
+ Section.
+
+ O. Preserve any Warranty Disclaimers.
+
+ If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no
+ material copied from the Document, you may at your option designate
+ some or all of these sections as invariant. To do this, add their
+ titles to the list of Invariant Sections in the Modified Version's
+ license notice. These titles must be distinct from any other
+ section titles.
+
+ You may add a section Entitled "Endorsements", provided it contains
+ nothing but endorsements of your Modified Version by various
+ parties--for example, statements of peer review or that the text
+ has been approved by an organization as the authoritative
+ definition of a standard.
+
+ You may add a passage of up to five words as a Front-Cover Text,
+ and a passage of up to 25 words as a Back-Cover Text, to the end of
+ the list of Cover Texts in the Modified Version. Only one passage
+ of Front-Cover Text and one of Back-Cover Text may be added by (or
+ through arrangements made by) any one entity. If the Document
+ already includes a cover text for the same cover, previously added
+ by you or by arrangement made by the same entity you are acting on
+ behalf of, you may not add another; but you may replace the old
+ one, on explicit permission from the previous publisher that added
+ the old one.
+
+ The author(s) and publisher(s) of the Document do not by this
+ License give permission to use their names for publicity for or to
+ assert or imply endorsement of any Modified Version.
+
+ 5. COMBINING DOCUMENTS
+
+ You may combine the Document with other documents released under
+ this License, under the terms defined in section 4 above for
+ modified versions, provided that you include in the combination all
+ of the Invariant Sections of all of the original documents,
+ unmodified, and list them all as Invariant Sections of your
+ combined work in its license notice, and that you preserve all
+ their Warranty Disclaimers.
+
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name
+ but different contents, make the title of each such section unique
+ by adding at the end of it, in parentheses, the name of the
+ original author or publisher of that section if known, or else a
+ unique number. Make the same adjustment to the section titles in
+ the list of Invariant Sections in the license notice of the
+ combined work.
+
+ In the combination, you must combine any sections Entitled
+ "History" in the various original documents, forming one section
+ Entitled "History"; likewise combine any sections Entitled
+ "Acknowledgements", and any sections Entitled "Dedications". You
+ must delete all sections Entitled "Endorsements."
+
+ 6. COLLECTIONS OF DOCUMENTS
+
+ You may make a collection consisting of the Document and other
+ documents released under this License, and replace the individual
+ copies of this License in the various documents with a single copy
+ that is included in the collection, provided that you follow the
+ rules of this License for verbatim copying of each of the documents
+ in all other respects.
+
+ You may extract a single document from such a collection, and
+ distribute it individually under this License, provided you insert
+ a copy of this License into the extracted document, and follow this
+ License in all other respects regarding verbatim copying of that
+ document.
+
+ 7. AGGREGATION WITH INDEPENDENT WORKS
+
+ A compilation of the Document or its derivatives with other
+ separate and independent documents or works, in or on a volume of a
+ storage or distribution medium, is called an "aggregate" if the
+ copyright resulting from the compilation is not used to limit the
+ legal rights of the compilation's users beyond what the individual
+ works permit. When the Document is included in an aggregate, this
+ License does not apply to the other works in the aggregate which
+ are not themselves derivative works of the Document.
+
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one half
+ of the entire aggregate, the Document's Cover Texts may be placed
+ on covers that bracket the Document within the aggregate, or the
+ electronic equivalent of covers if the Document is in electronic
+ form. Otherwise they must appear on printed covers that bracket
+ the whole aggregate.
+
+ 8. TRANSLATION
+
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section
+ 4. Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License, and all the license notices in the
+ Document, and any Warranty Disclaimers, provided that you also
+ include the original English version of this License and the
+ original versions of those notices and disclaimers. In case of a
+ disagreement between the translation and the original version of
+ this License or a notice or disclaimer, the original version will
+ prevail.
+
+ If a section in the Document is Entitled "Acknowledgements",
+ "Dedications", or "History", the requirement (section 4) to
+ Preserve its Title (section 1) will typically require changing the
+ actual title.
+
+ 9. TERMINATION
+
+ You may not copy, modify, sublicense, or distribute the Document
+ except as expressly provided under this License. Any attempt
+ otherwise to copy, modify, sublicense, or distribute it is void,
+ and will automatically terminate your rights under this License.
+
+ However, if you cease all violation of this License, then your
+ license from a particular copyright holder is reinstated (a)
+ provisionally, unless and until the copyright holder explicitly and
+ finally terminates your license, and (b) permanently, if the
+ copyright holder fails to notify you of the violation by some
+ reasonable means prior to 60 days after the cessation.
+
+ Moreover, your license from a particular copyright holder is
+ reinstated permanently if the copyright holder notifies you of the
+ violation by some reasonable means, this is the first time you have
+ received notice of violation of this License (for any work) from
+ that copyright holder, and you cure the violation prior to 30 days
+ after your receipt of the notice.
+
+ Termination of your rights under this section does not terminate
+ the licenses of parties who have received copies or rights from you
+ under this License. If your rights have been terminated and not
+ permanently reinstated, receipt of a copy of some or all of the
+ same material does not give you any rights to use it.
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+ The Free Software Foundation may publish new, revised versions of
+ the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ <http://www.gnu.org/copyleft/>.
+
+ Each version of the License is given a distinguishing version
+ number. If the Document specifies that a particular numbered
+ version of this License "or any later version" applies to it, you
+ have the option of following the terms and conditions either of
+ that specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If the
+ Document does not specify a version number of this License, you may
+ choose any version ever published (not as a draft) by the Free
+ Software Foundation. If the Document specifies that a proxy can
+ decide which future versions of this License can be used, that
+ proxy's public statement of acceptance of a version permanently
+ authorizes you to choose that version for the Document.
+
+ 11. RELICENSING
+
+ "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
+ World Wide Web server that publishes copyrightable works and also
+ provides prominent facilities for anybody to edit those works. A
+ public wiki that anybody can edit is an example of such a server.
+ A "Massive Multiauthor Collaboration" (or "MMC") contained in the
+ site means any set of copyrightable works thus published on the MMC
+ site.
+
+ "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
+ license published by Creative Commons Corporation, a not-for-profit
+ corporation with a principal place of business in San Francisco,
+ California, as well as future copyleft versions of that license
+ published by that same organization.
+
+ "Incorporate" means to publish or republish a Document, in whole or
+ in part, as part of another Document.
+
+ An MMC is "eligible for relicensing" if it is licensed under this
+ License, and if all works that were first published under this
+ License somewhere other than this MMC, and subsequently
+ incorporated in whole or in part into the MMC, (1) had no cover
+ texts or invariant sections, and (2) were thus incorporated prior
+ to November 1, 2008.
+
+ The operator of an MMC Site may republish an MMC contained in the
+ site under CC-BY-SA on the same site at any time before August 1,
+ 2009, provided the MMC is eligible for relicensing.
+
+ADDENDUM: How to use this License for your documents
+====================================================
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+ Copyright (C) YEAR YOUR NAME.
+ 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''.
+
+ If you have Invariant Sections, Front-Cover Texts and Back-Cover
+Texts, replace the "with...Texts." line with this:
+
+ with the Invariant Sections being LIST THEIR TITLES, with
+ the Front-Cover Texts being LIST, and with the Back-Cover Texts
+ being LIST.
+
+ If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+ If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of free
+software license, such as the GNU General Public License, to permit
+their use in free software.
+
+
+
+Tag Table:
+Node: Top803
+Node: Introduction2905
+Ref: Introduction-Footnote-13656
+Node: Installation3703
+Node: Activation4820
+Ref: Activation-Footnote-15487
+Node: Feedback5613
+Ref: Feedback-Footnote-16031
+Node: Navigation mode6252
+Node: Record navigation7990
+Node: Field navigation8944
+Node: Field folding9620
+Node: Field edition10366
+Node: Searches12160
+Node: Statistics12936
+Node: Data integrity14005
+Node: Edition modes14517
+Ref: Edition modes-Footnote-116192
+Node: Configuration16223
+Node: Finding the recutils16524
+Node: Records appearance17138
+Node: GNU Free Documentation License17641
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End:
diff --git a/rec-mode.texi b/rec-mode.texi
new file mode 100644
index 0000000..3127ef4
--- /dev/null
+++ b/rec-mode.texi
@@ -0,0 +1,469 @@
+\input texinfo
+@comment %**start of header
+@setfilename rec-mode.info
+@settitle rec-mode for Emacs
+@set UPDATED 7 November 2020
+@set UPDATED-MONTH November 2020
+@set EDITION 1.8.90
+@set VERSION 1.8.90
+@afourpaper
+@comment %**end of header
+
+@c Macros used in this file.
+
+@macro ie
+@i{i.e.@:}
+@end macro
+
+@macro reccmd{key,command}
+@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
+@end macro
+
+@copying
+This manual is for rec-mode for Emacs, which is part of the GNU
+recutils suite (version @value{VERSION}, @value{UPDATED}).
+
+Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
+2020 Jose E. Marchesi
+
+@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
+
+@dircategory Database
+@direntry
+* rec-mode: (rec-mode). Emacs mode for editing recfiles.
+@end direntry
+
+@titlepage
+@title rec-mode: an Emacs mode for editing recfiles
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author by Jose E. Marchesi
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top rec-mode: an Emacs mode for editing recfiles
+
+This manual documents version @value{VERSION} of rec-mode.
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Introduction:: Getting started
+* Navigation mode:: User-friendly interface for browing recfiles
+* Edition modes:: Edit recfiles in rec-format
+* Configuration:: Adapting rec-mode to your needs
+* GNU Free Documentation License:: Distribution terms for this document
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Installation:: How to install rec-mode
+* Activation:: How to activate rec-mode for certain buffers
+* Feedback:: Bug reports, ideas, patches etc.
+
+Navigation mode
+
+* Record navigation:: Moving through records.
+* Field navigation:: Moving through fields in a record.
+* Field folding:: Hiding and showing the values of fields.
+* Field edition:: Changing the values of fields.
+* Searches:: Finding records fufilling some criteria.
+* Statistics:: Counting records.
+* Data integrity:: Verifying the integrity of the recfile.
+
+Edition modes
+
+* Edition modes:: Edit recfiles in rec-format
+
+Configuration
+
+* Finding the recutils:: Specifying the location of the recutils.
+* Records appearance:: Setting the way records are displayed.
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+rec-mode is a mode for browsing and editing recfiles, which are text
+files containing data structured in fields and records. It is part of
+the GNU recutils@footnote{@url{http://www.gnu.org/software/recutils}}
+suite.
+
+
+Recfiles are text-based databases which are easy to read and write
+manually using a text editor. At the same time they feature enough
+structure so they can be read, edited and processed automatically by
+programs.
+
+@menu
+* Installation:: How to install rec-mode
+* Activation:: How to activate rec-mode for certain buffers
+* Feedback:: Bug reports, ideas, patches etc.
+@end menu
+
+@node Installation
+@section Installation
+
+rec-mode is implemented in a self-contained elisp file called
+@file{rec-mode.el}. It can be obtained in several ways:
+
+@itemize @minus
+@item As part of a released tarball of recutils. @file{rec-mode.el}
+can be found in the @file{etc/} directory in the tarball contents.
+@item As part of the source tree cloned from the development git
+repo. @file{rec-mode.el} can be found in the @file{etc/} directory in
+the recutils sources tree.
+@item As a single file downloaded form some other location in
+internet.
+@item It may be already installed as part of a binary package in some
+distribution.
+@end itemize
+
+@noindent In the first three cases you need to tell Emacs where to locate the
+@file{rec-mode.el} file and to load it. Add the following to your
+@file{.emacs} file.
+@lisp
+(add-to-list 'load-path "~/path/to/recmode/")
+(require 'rec-mode)
+@end lisp
+
+@noindent If @file{rec-mode.el} was installed as part of a binary
+package in a distribution then you usually don't have to touch the
+@code{load-path} variable. Depending on the specific case you may
+have to @code{require} the package.
+
+@node Activation
+@section Activation
+@cindex activation
+
+To make sure files with extension @file{.rec} use rec-mode, add the
+following line to your @file{.emacs} file.
+@lisp
+(add-to-list 'auto-mode-alist '("\\.rec\\'" . rec-mode))
+@end lisp
+@noindent rec-mode buffers need font-lock to be turned on - this is
+the default in Emacs@footnote{If you don't use font-lock globally,
+turn it on in the rec buffer with @code{(add-hook 'rec-mode-hook
+'turn-on-font-lock)}}.
+
+With this setup, all files with extension @samp{.rec} will be put into
+rec mode. As an alternative, make the first line of a recfile look
+like this:
+
+@example
+# -*- mode: rec -*-
+@end example
+
+@noindent which will select rec-mode for this buffer no matter what
+the file's name is.
+
+@node Feedback
+@section Feedback
+@cindex feedback
+@cindex bug reports
+@cindex maintainer
+@cindex author
+
+If you find problems with rec-mode, or if you have questions, remarks,
+or ideas about it, please mail to the recutils mailing list
+@email{bug-recutils@@gnu.org}. If you are not a member of the mailing
+list, your mail will be passed to the list after a moderator has
+approved it@footnote{Please consider subscribing to the mailing list,
+in order to minimize the work the mailing list moderators have to do.
+The subscription can be done online at
+@url{http://lists.gnu.org/mailman/listinfo/bug-recutils}.}.
+
+@node Navigation mode
+@chapter Navigation mode
+
+When a recfile is visited in Emacs and rec-mode is activated, the
+contents of the file are examined and parsed in order to determine if
+it is a valid recfile and, in that case, to extract information like
+the kind of records stored in the file.
+
+If the file does not contain valid rec data then the buffer is put in
+@code{fundamental-mode} and a description of the syntax error, along
+its location, is notified in the echo area.
+
+If the file contains valid rec data, the mode sets itself in what is
+known as ``navigation mode''. In this mode the buffer is made
+read-only and it is narrowed to the first record present in the file.
+Also, the presentation of the record contents is slightly changed in
+order to improve the visualization of the data: continuation line
+marks are replaced by indentation, big fields are folded, etc. The
+modeline is changed in order to reflect the type of the records being
+navigated.
+
+At this point the user can navigate through the records and fields
+contained in the file, and edit the contents of the fields and the
+structure of the records, by using the commands described in the
+following subsections.
+
+@menu
+* Record navigation:: Moving through records
+* Field navigation:: Moving through fields in a record
+* Field folding:: Hiding and showing the values of fields
+* Field edition:: Changing the values of fields
+* Searches:: Finding records fulfilling some criteria
+* Statistics:: Counting records
+* Data integrity:: Verifying the integrity of the recfile
+@end menu
+
+@node Record navigation
+@section Record navigation
+@cindex motion, between records
+@cindex jumping, to records
+@cindex record navigation
+
+The following commands jump to other records in the buffer.
+
+@table @asis
+@reccmd{n,rec-cmd-goto-next-rec}
+Display the next record of the same type in the buffer.
+@*`C-u N n' will move next N times.
+@reccmd{p,rec-cmd-goto-previous-rec}
+Display the previous record of the same type in the buffer.
+@*`C-u N p' will move backwards N times.
+@reccmd{d, rec-cmd-show-descriptor}
+Display the record descriptor applicable to the current record. If
+the current record is anonymous, @ie{} there is not record
+descriptor. then this command does nothing.
+@reccmd{b, rec-cmd-jump-back}
+Display the record previously displayed in the buffer.
+@reccmd{C-c t, rec-find-type}
+Prompt the user for one of the record types present in the recfile and
+display the first record of the selected type.
+@end table
+
+@node Field navigation
+@section Field navigation
+
+The following commands iterate through the fields in a record, and to
+get information about some of the properties of the fields.
+
+@table @asis
+@reccmd{TAB, rec-cmd-goto-next-field}
+Move the cursor to the beginning of the name of the next field in the
+current record. If the cursor is currently located at the last field
+of the record then move it to the beginning of the first field.
+@reccmd{t, rec-cmd-show-type}
+Show information about the type of the field under the cursor, if it
+is defined.
+@end table
+
+@node Field folding
+@section Field folding
+
+Fields in recfiles can contain data of any size, and sometimes it is
+difficult to have an overview of the contents of the record. The
+following commands fold and unfold the value of the field under the
+cursor.
+
+@table @asis
+@reccmd{SPC, rec-cmd-toggle-field-visibility}
+Toggle the visibility of the field under the cursor. When a field is
+folded then three dots are displayed in the buffer instead of the
+value of the field.
+
+It is possible to automatically fold any field whose value exceeds a
+certain limit which can be configured by the user. @xref{Records
+appearance}.
+@end table
+
+@node Field edition
+@section Field edition
+
+The following commands change the value of the field under the cursor.
+
+@table @asis
+@reccmd{e, rec-cmd-edit-field}
+Edit the value of the field under the cursor. The specific action
+depends on the type of the field in the corresponding record
+descriptor:
+@itemize @minus
+@item For @b{date} fields a calendar buffer is opened in another window
+and the focus is moved there. The user can then select a date by
+moving the cursor there and press @kbd{RET} in order to set that date
+as the value for the field. Alternatively the user can press @kbd{t}
+in order to set the field to ``now'', or @kbd{q} to cancel the
+operation. In the later case the value of the field is left
+untouched.
+@item For @b{enumerated} and @b{bool} fields a fast-select buffer is opened in
+another window, showing a list of labeled options. The labels are
+single digits and letters. The user can then select ony of the
+options by pressing the corresponding label, or cancel the operation
+by pressing @kbd{RET}. In the later case the value of the field is
+left untouched.
+@item For any other kind of fields an edition buffer is opened in
+another window, showing the current contents of the field. The user
+can then edit the buffer as desired. When she is done, the user can
+then press @kbd{C-c C-c} in order to set the new value of the field,
+or just kill the buffer to cancel the operation.
+@end itemize
+@reccmd{m, rec-cmd-trim-field-value}
+Trim the value of the field under the cursor, removing any sequence of
+leading and trailing blank characters.
+@end table
+
+@node Searches
+@section Searches
+
+The following commands jump to the first record in the buffer
+satisfying some criteria.
+
+@table @asis
+@reccmd{s q, rec-cmd-select-fast}
+Display the first record having a field whose value matches a given
+fixed pattern. This is equivalent of using the command line option
+@option{-q} of @command{recsel}. If a prefix argument is specified
+then the search is case-insensitive.
+@reccmd{s s, rec-cmd-select-sex}
+Display the first record in the buffer satisfying a given selection
+expression. This is equivalent of using the command line option
+@option{-e} of @command{recsel}. If a prefix argument is specified
+then the search is case-insensitive.
+@end table
+
+@node Statistics
+@section Statistics
+
+The following commands allow to count records in the current buffer
+based on some provided criteria.
+
+@table @asis
+@reccmd{I, rec-cmd-show-info}
+Show the number of records in the buffer categorized by type.
+@reccmd{#, rec-cmd-count}
+Count the number of records in the buffer having the same type as the
+current record. With a numeric prefix N, ask for a selection
+expression and count the number of records in the buffer satisfying
+the expression.
+
+Note that rec-mode tries to guess a reasonable default for the
+selection expression, depending on the type of the field and its
+value. If the user press @kbd{RET} then the provided default
+selection expression is used.
+@reccmd{%, rec-cmd-statistics}
+If the field under the cursor contains an enumerated value, show the
+percentages of records in the current record set having fields with
+each of the possible values of the enumerated type.
+@end table
+
+@node Data integrity
+@section Data integrity
+
+The integrity of the rec data stored in the file can be checked using
+the following commands.
+
+@table @asis
+@reccmd{c, rec-cmd-compile}
+Compile the buffer with @command{recfix} and open a compilation window
+showing the result of the command. In case some error or warning is
+reported, the user can jump to the location triggering the error by
+pressing @kbd{RET} in the compilation window.
+@end table
+
+@node Edition modes
+@chapter Edition modes
+
+The navigation mode described in a previous chapter is mainly intended
+for browsing recdata and doing changes at the record level: editing
+the contents of a field, adding or removing fields, etc. In order to
+perform broader changes, such as adding/deleting record descriptors,
+records or comment blocks, the user must enter into one of the
+``edition modes''.
+
+There are three edition modes, covering different areas of the
+recfile: record, record type and buffer. When an edition mode is
+entered the buffer is set in read/write mode, it is narrowed to the
+desired area and any embellishment used in navigation mode is
+removed@footnote{Exceptuating font-lock}. As a general rule, the
+commands available in navigation mode are also available in the
+edition mode prefixed with @kbd{C-c}. Thus, @kbd{C-c n} would make
+the cursor to jump to the beginning of the next record.
+
+The following commands are used to enter into one of the available
+edition modes from the navigation mode.
+
+@table @asis
+@reccmd{R, rec-edit-record}
+Edit the record being navigated.
+@reccmd{T, rec-edit-type}
+Edit the record set being navigated.
+@reccmd{B, rec-edit-buffer}
+Edit the buffer.
+@end table
+
+@noindent After doing modifications in the buffer, the user can go
+back to navigation mode by using the following command.
+
+@table @asis
+@reccmd{C-c C-c, rec-finish-editing}
+Finish the current edition and return to navigation mode. If a
+syntactic error was introduced in the edition activity then the error
+is reported in the echo area and navigation mode is not entered.
+@end table
+
+@node Configuration
+@chapter Configuration
+
+TBC
+
+@menu
+* Finding the recutils:: Specifying the location of the recutils.
+* Records appearance:: Setting the way records are displayed
+@end menu
+
+@node Finding the recutils
+@section Finding the recutils
+
+@code{rec-mode} makes use of the several utilities which are part of
+the recutils. The following variables tell the mode where to find the
+utilities. The default values of these variables must work if the
+recutils are installed system-wide in the system.
+
+@table @code
+@item rec-recsel
+Name of the @command{recsel} utility from the GNU recutils.
+@item rec-recinf
+Name of the @command{recinf} utility from the GNU recutils.
+@item rec-recfix
+Name of the @command{recfix} utility from the GNU recutils.
+@end table
+
+@node Records appearance
+@section Records appearance
+
+The appearance of the records in navigation mode can be customised by
+tweaking the value of the following variables.
+
+@table @code
+@item rec-max-lines-in-fields
+Values in fiels having more than the specified number of lines will be
+hidden by default in navigation mode. When hidden, an ellipsis is
+shown instead of the value of the field. Default is @code{15}.
+@end table
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
+
+@bye
--
2.24.3 (Apple Git-128)
- [PATCH 1/3] Font lock fixes and many small checkdoc fixes, (continued)
- [PATCH 1/3] Font lock fixes and many small checkdoc fixes, Antoine Kalmbach, 2020/11/11
- [PATCH 2/3] Docstring improvements (via checkdoc), Antoine Kalmbach, 2020/11/11
- Re: [PATCH 2/3] Docstring improvements (via checkdoc), Jose E. Marchesi, 2020/11/11
- Re: [PATCH 2/3] Docstring improvements (via checkdoc), Antoine Kalmbach, 2020/11/11
- Re: [PATCH 2/3] Docstring improvements (via checkdoc), Jose E. Marchesi, 2020/11/11
- Re: [PATCH 2/3] Docstring improvements (via checkdoc), Antoine Kalmbach, 2020/11/11
- Re: [PATCH 2/3] Docstring improvements (via checkdoc), Jose E. Marchesi, 2020/11/11
- Re: [PATCH 2/3] Docstring improvements (via checkdoc), Antoine Kalmbach, 2020/11/11
[PATCH 3/3] Add Info mode manual,
Antoine Kalmbach <=