diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bd3c126 --- /dev/null +++ b/.gitignore @@ -0,0 +1,80 @@ +*~ +*.bak +*.o +*.orig +*.patch +*.swp +.deps +.libs +Makefile +Makefile.in + +core +.gdb_history +.gdbinit + +/src/nanofur +/src/revision.h + +/ABOUT-NLS +/INSTALL +/aclocal.m4 +/ar-lib +/autom4te.cache +/compile +/config.cache +/config.guess +/config.h +/config.h.in +/config.log +/config.rpath +/config.status +/config.sub +/configure +/depcomp +/install-sh +/intl +/missing +/mkinstalldirs +/stamp-h1 + +# Gettext m4 files: +/m4/codeset.m4 +/m4/extern-inline.m4 +/m4/fcntl-o.m4 +/m4/gettext.m4 +/m4/glibc2.m4 +/m4/glibc21.m4 +/m4/iconv.m4 +/m4/intdiv0.m4 +/m4/intl.m4 +/m4/intldir.m4 +/m4/intlmacosx.m4 +/m4/intmax.m4 +/m4/inttypes-pri.m4 +/m4/inttypes_h.m4 +/m4/lcmessage.m4 +/m4/lib-ld.m4 +/m4/lib-link.m4 +/m4/lib-prefix.m4 +/m4/lock.m4 +/m4/longlong.m4 +/m4/nls.m4 +/m4/po.m4 +/m4/printf-posix.m4 +/m4/progtest.m4 +/m4/size_max.m4 +/m4/stdint_h.m4 +/m4/threadlib.m4 +/m4/uintmax_t.m4 +/m4/visibility.m4 +/m4/wchar_t.m4 +/m4/wint_t.m4 +/m4/xsize.m4 + +# Gnulib stuff: +/gnulib/ +/lib/ +/m4/.gitignore +/m4/gnulib-cache.m4 +/snippet/ diff --git a/AUTHORS b/AUTHORS new file mode 100644 index 0000000..5628a16 --- /dev/null +++ b/AUTHORS @@ -0,0 +1,76 @@ +This file lists people who have made significant contributions to the +nanofur editor. Please see the ChangeLog for specific changes by author. +---------------------------------------------------------------------- + +Chris Allegretta + * Original program author and long-time maintainer. + +Benno Schulenberg + * An array of small bug fixes, the cut-word and block-jump + routines, text selection by holding Shift, macro recording + and replay, extra key bindings, the --indicator, --minibar, + and --zero options, and braced functions in string binds. + Current maintainer. + +David Lawrence Ramsey + * Multiple-buffer support, operating-dir option (-o), bug fixes + for display routines, wrapping code, spelling fixes, parts of + UTF-8 support, softwrap overhaul, constantshow mode, undoable + indentations, undoable justifications, justifiable regions, + and numerous other fixes. Former stable-series maintainer. + +Jordi Mallach + * Debian package maintainer, fellow bug squasher, translator + for Catalan. Former head of internationalization support. + +Adam Rogoyski + * New write_file() function, read_file() optimization, mouse + support, resize support, nohelp (-x) option, justify function, + follow symlink option and bugfixes, and much more. + +Robert Siemborski + * Miscellaneous cut, display, replace, and other bug fixes, + original and new "magic line" code, read_line() function, + new edit display routines. + +Rocco Corsi + * Internal spelling code, many optimizations and bug fixes + for findnextstr() and search-related functions, various + display and file-handling fixes. + +David Benbennick + * Wrap and justify bugfixes/enhancements, new color syntax + code, memleak fixes, parts of the UTF-8 support, and other + miscellaneous fixes. + +Mike Frysinger + * Whitespace display mode, --enable-utf8/--disable-utf8 configure + options for ncurses, many new color regexes and improvements to + existing ones in syntax/*.nanofurrc, the move from svn to git, the + conversion to gnulib, and miscellaneous bug fixes. Former + Gentoo package maintainer. + +Mark Majeres + * A functional undo/redo system, and coloring nanofur's interface. + +Mahyar Abbaspour + * Improved handling of SIGWINCH. + +Mike Scalora + * The comment/uncomment feature. + +Faissal Bensefia + * Line numbers. + +Sumedh Pendurkar + * The word-completion feature. + +Rishabh Dave + * Searchable help. + +Marco Diego Aurélio Mesquita + * Filtering text through an external command. + * Placing anchors (bookmarks) and jumping to them. + +Brand Huntsman + * The delayed parsing of syntax files. diff --git a/COPYING b/COPYING new file mode 100644 index 0000000..4432540 --- /dev/null +++ b/COPYING @@ -0,0 +1,676 @@ + + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + 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, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public 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. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program 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. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. + diff --git a/COPYING.DOC b/COPYING.DOC new file mode 100644 index 0000000..4a0fe1c --- /dev/null +++ b/COPYING.DOC @@ -0,0 +1,397 @@ + GNU Free Documentation License + Version 1.2, November 2002 + + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + 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. + +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 for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +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. + + +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.2 + 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. diff --git a/ChangeLog b/ChangeLog new file mode 100644 index 0000000..9798088 --- /dev/null +++ b/ChangeLog @@ -0,0 +1,1408 @@ +Changes between v8.1 and v8.2: +------------------------------ + +Benno Schulenberg (22): + bindings: at a Yes-No-All prompt, accept also ^A for "All" + bindings: let the central numpad key (with Ctrl) center the current line + bump version numbers and add a news item for the 8.2 release + docs: do not quote the argument of 'include' statements in sample nanofurrc + docs: mention former maintainership last among an author's contributions + docs: mention the availability of ^Y, ^N, and ^A at a Yes-No prompt + docs: trim stuff that is more than four years old from the changelog + gnulib: update to its current upstream state + macro: insert it in keystroke buffer without discarding latter's contents + moving: for Alt+Home/Alt+End, refresh the screen when the mark is on + syntax: autoconf: colorize the keywords 'case', 'esac', and 'ifelse' too + syntax: awk: add a missing "|" between "\?" and ":" + syntax: awk: colorize escape sequences specially + syntax: awk: rewrite a regex more densely, and add the missing ~ operator + syntax: man: colorize also the .MT .ME .EX .EE .SY .OP and .YS macros + syntax: nanofurrc: an unquoted argument of 'include' may not contain blanks + tweaks: delete three redundant checks from the undo/redo code + tweaks: improve or rewrap six comments, and add two missing ones + tweaks: move a condition to the only place that needs it + tweaks: rename a symbol, away from an obscure abbreviation + tweaks: reshuffle a seldom-used function to the end of an if-else series + tweaks: unwrap three lines that don't need to be wrapped + +Collin Funk (1): + build: update a symbol that was renamed in gnulib + + +Changes between v8.0 and v8.1: +------------------------------ + +Benno Schulenberg (56): + bindings: let ^L put the cursor line at center, then top, then bottom + build: check for the correct function in an #ifdef + build: require version 0.20 of gettext for building nanofur from git + build: use the standard `autoreconf` invocation + bump version numbers and add a news item for the 8.1 release + docs: add 'set colonparsing' to the sample nanofurrc + docs: add the Alt+Home/Alt+End shortcuts to the cheatsheet + docs: avert hyphenation of the technical words "ncurses" and "terminfo" + docs: correct the description of --bold, as function tags are unaffected + docs: document the new --listsyntaxes (-z) option + docs: don't say any more that -z was removed, as it has been repurposed + docs: explain the behavior of the new function `cycle` + docs: explain the details of --colonparsing / -@ / 'set colonparsing' + docs: extend the FAQ item about urxvt modified keys, with M-Home/M-End + docs: properly escape a literal '@' in the texi document + docs: remove the 'filename:linenumber' format from the synopsis + files: avoid mistakenly setting the column number to a given line number + files: look for digits and colons starting from the end of the filename + files: when a filename with a colon and digits exists, open that file + files: with --rectrict, prevent invoking the browser and toggling backups + general: disable the type-ahead checking that ncurses normally does + gnulib: update to its current upstream state + help: regroup the `center` item, placing it with the new `cycle` + help: show option -Y/--syntax in --help output also in restricted mode + input: drop recognition of the urxvt escape sequences for M-Home/M-End + input: make sure that a string-bind return value is non-negative + input: provide for urxvt setting a high bit or sending an extra escape + input: recognize the raw Xterm escape sequences for Alt+Home and Alt+End + minibar: do not falsely report that a new, empty file is in Mac format + moving: use edit_scroll() only when scrolling one row is enough + new feature: add bindable function `cycle` that pushes cursor line around + new feature: option -z lists the names of available syntaxes + options: remove the deprecated synonym -$ of -S/--softwrap + options: require --colonparsing/-@ to parse colon+number after a filename + rcfile: remove old bindable function 'nowrap', alias of 'breaklonglines' + startup: do not activate --modernbindings when name starts with "e" + syntaxes: mention the original author of most of the syntax files + syntax: man: colorize some of the things that manipulate hyphenation + syntax: patch: recognize also the .rej extension + text: do not check for + mark while getting input but in do_tab() + tweaks: add a space after a '+', for consistent formatting + tweaks: discard a bracketed paste in the help viewer with fewer beeps + tweaks: drop two redundant conditions + tweaks: elide unhelpful occurrences of the word "will" + tweaks: exclude the colon-parsing code from the tiny version + tweaks: extend the deprecation period of 'set nowrap' and prefix 'bright' + tweaks: implement do_center() with a single call instead of three + tweaks: in FAQ, use 'id' attribute instead of empty anchor with 'name' + tweaks: make a comment more accurate, and unabbreviate a variable name + tweaks: make the inclusion condition for do_center() more strict + tweaks: remove the now unneeded special keycode INDENT_KEY + tweaks: reshuffle a declaration, adjust a comment, normalize indentation + tweaks: reshuffle some lines, to put vaguely related things together + tweaks: rewrap some lines, for more even lengths + tweaks: simplify a condition, to match the same condition five lines back + tweaks: slightly reword a phrase in the explanation of --colonparsing + +Jaroslav Fowkes (1): + syntax: fortran: fix a typo (a missing backslash) + + +Changes between v7.2 and v8.0: +------------------------------ + +Andy Koppe (2): + input: scroll on mousewheel events instead of moving the cursor + rcfile: map the gray #rgb codes (#111 to #EEE) to the xterm grayscale + +Benjamin Valentin (1): + new feature: interpret also : when opening a file + +Benno Schulenberg (155): + bindings: allow speller and friends to be rebound also in restricted mode + bindings: in the tiny version, bind M-6 only in main, not at the prompts + bindings: let move the cursor to top/bottom of viewport + bindings: let M-" place/remove an anchor, and let M-' jump to one + bindings: let M-& show the ncurses version+patch, as a small Easter egg + bindings: make ^F start a forward search by default + bindings: make ^F start a forward search by default + bindings: set up modern bindings also when binary's name starts with "e" + bindings: show ^- instead of ^/ for 'flipgoto' when on a Linux console + bindings: with --modern, do not let ^Q^Q quit nanofur without saving + bindings: with --modern, use ^H for Help when the terminal allows it + browser: report an error instead of crashing when the folder disappears + browser: restore typing position at prompt after "^R name ^T ^F ^V ^C" + bump version numbers and add a news item for the 8.0 release + chars: add a helper function for stripping leading blanks from a string + copyright: update the years for the FSF + display: add a wnoutrefresh() call for NetBSD, to force a cursor update + display: do not attempt to draw a line that is outside the viewport + display: draw a new magic line rightaway when there are multiline regexes + display: show the help lines down to the tiniest possible terminal size + docs: add a caveat in the FAQ about bracketed pastes + docs: add a clarifying note to the description of --tabstospaces + docs: add an example binding for normalizing Unicode to the sample nanofurrc + docs: add a reference to the 'help-nanofur' mailing list + docs: add M-C and M-Z to the cheatsheet, and reshuffle for balance + docs: add ^T^S (spell check) and M-S (softwrap) to the cheatsheet + docs: add two examples of custom key bindings to the nanofurrc manpage + docs: adjust an example help line in the README to the current state + docs: adjust the cheatsheet for the changed meanings of ^F, ^B, M-F, M-B + docs: clarify that a fileregex is matched against the absolute filename + docs: delete a remark about libvte that is no longer relevant + docs: describe nanofur more specifically as a text editor + docs: document the : thing for cursor positioning + docs: document the new bindable functions 'toprow' and 'bottomrow' + docs: document the new --modernbindings option + docs: fix a ten-year-old typo, reported by `correctmost` + docs: improve the description of the 'flipexecute' bindable function + docs: in a synopsis, use braces around a choice of required parts + docs: in the sample nanofurrc, set the guidestripe to a soft grey + docs: mention backreferences (for replacements with regular expressions) + docs: mention how to get the old behavior of ^F, ^B, M-F, and M-B back + docs: mention that a restricted nanofur does not access the history files + docs: mention that 'light' background colors do not work on Linux console + docs: mention that --modernbindings overrides --preserve + docs: mention the changed meanings of ^F/^B and also in the texi manual + docs: mention the missing two options that override --bold + docs: say "mini bar", not "minibar", when referring to the actual bar + docs: trim stuff that is more than five years old from the changelog + docs: use a space after #, like everywhere else in the sample nanofurrc + editing: adjust the mark before trimming redundant blanks + execute: show "Older" and "Newer" in the help lines, to allow rebinding + feedback: drop an unnecessary warning, to not bother the user + feedback: lowercase a letter, as the phrase is not a full sentence + feedback: raise the level of "Macro is empty", to match similar messages + feedback: suppress filename and linecount when --zero is active + feedback: suppress format-conversion messages for --zero and --mini + files: do not allow M-U to remove text read from standard input + files: run `chmod` and `chown` on the descriptor, not on the filename + formatter: do not crash when the formatter command is empty + general: include the Copy function (M-6 or ^C) into the tiny version + general: let the constant-show toggle override the zero-interface mode + gnulib: update to current upstream state, to make a fresh checkout work + gnulib: update to its current upstream state + help: give the "Replace with" prompt its own help text + help: mention M-Home and M-End in the help text and help lines + help: rebalance the help items when --preserve is used + help: restore ^H and ^D as the primary shortcuts for Backspace and Delete + help: show ^F/^B as primary shortcuts for search, not as secondary + indicator: do not oversize the scroller when softwrapping + input: avoid hanging after a 39-character paste on a VSCode terminal + input: flush the keystroke buffer upon any kind of error condition + input: for one bump of the mousewheel scroll two lines, not three + input: intercept a spurious keycode and say what the actual problem is + input: let the handler of string binds return a byte whenever possible + input: neutralize two spurious keycodes from VTE terminals + input: prevent 'macro_length' from underflowing when hammering M-: + input: recognize certain escape sequences for F13 to F16 again + input: snip the `recordmacro` and `runmacro` keystrokes in a better way + input: store key codes in the macro buffer as they come in from ncurses + input: store keystroke in macro buffer only when about to interpret it [reverted] + justify: keep as much of the marked region onscreen as possible + justify: keep the cursor at the original end of a marked region + justify: recompute the multidata for paragraphs larger than the viewport + justify: set the correct starting point also with --cutfromcursor + justify: set `x = 0` for the undo item, for when using --cutfromcursor + linter: do not mess up the input stream when the linter command is empty + linter: use a format string, to deflect format-string attacks + memory: prevent a leak by freeing a possibly already existing color combo + minibar: mention the file format when it's DOS or Mac + moving: preserve horizontal position when jumping to top or bottom row + new feature: functions that jump to the top or bottom of the viewport + new feature: option --modernbindings sets up more widespread key bindings + options: make --modernbindings actually override --preserve + rcfile: add bindable functions for moving the cursor to top or bottom row + rcfile: avoid crashing on an include path that is way too long + replacing: stash the string to be replaced while asking for replacement + revert the previous commit -- forget about -? as a synonym for --help + screen: recalculate the multidata when detecting the need for it + search: avoid a crash after a nested search, reported by `correctmost` + search: avoid crashing after searching a help text during a regex replace + shutdown: ignore a modified buffer when in view mode + softwrap: adjust start-of-screen when the 'edittop' line is hard-wrapped + softwrap: realign start-of-screen when redoing an automatic hard-wrap + softwrap: remember the actual breaking point when wrapping at blanks + startup: use a format string, to deflect format-string attacks + syntax: c: require a preceding blank when a line comment contains a quote + syntax: javascript: recognize also the .mjs extension + syntax: makefile: ensure that the key always produces a tab + syntax: makefile, sh: recognize also a fresh Makefile and fresh .profile + syntax: nanofurrc: colorize {toprow} and {bottomrow} for string binds + syntax: sh: recognize more shells than `sh` on a shebang line for busybox + tweaks: add a comment that refers to the VTE spurious-code issue + tweaks: add a missing 'type' attribute to a + + + + +

The GNU nanofur editor FAQ

+

Table of Contents

+

1. General

+

+ 1.1. What is GNU nanofur?
+ 1.2. What is the history behind nanofur?
+ 1.3. Why the name change from TIP?
+ 1.4. What is the current version of nanofur?
+ 1.5. I want to read the manpage without having to download the program! +

+

2. Where to get GNU nanofur.

+

+ 2.1. FTP and WWW sites that carry nanofur.
+ 2.2. RedHat and derivatives (.rpm) packages.
+ 2.3. Debian (.deb) packages.
+ 2.4. By git (for the brave). +

+

3. Installation and Configuration

+

+ 3.1. How do I install the RPM or DEB package?
+ 3.2. Compiling from source: WHAT THE HECK DO I DO NOW?
+ 3.3. Why does everything go into /usr/local?
+ 3.4. nanofur should automatically run strip on the binary when installing it!
+ 3.5. How can I make the executable smaller? This is too bloated!
+ 3.6. Tell me more about this multibuffer stuff!
+ 3.7. Tell me more about this verbatim input stuff!
+ 3.8. How do I make a .nanofurrc file that nanofur will read when I start it?
+ 3.9. Why does my self-compiled nanofur not read /etc/nanofurrc?
+

+

4. Running

+

+ 4.1. Alt+Up does nothing on a Linux console. How can I make it scroll?
+ 4.2. How can I make Ctrl+Shift+Left/Right select words on urxvt?
+ 4.3. Ack! My numeric keypad's keys don't work properly when NumLock is off! What can I do?
+ 4.4. With what keystroke can I paste text from the clipboard into nanofur?
+ 4.5. How do I select text for or paste text from the clipboard when nanofur's mouse support is turned on?
+ 4.6. When I paste text into a document, each line gets indented further than the last. Why? And how can I stop this?
+ 4.7. When I paste from Windows into a remote nanofur, nanofur rewraps the lines. What gives?
+ 4.8. I've compiled nanofur with color support, but I don't see any color when I run it!
+ 4.9. How do I make nanofur my default editor (in Pine, mutt, etc.)?
+

+

5. Internationalization

+

+ 5.1. There's no translation for my language!
+ 5.2. I don't like the translation for <x> in my language. How can I fix it?
+ 5.3. What is the status of Unicode support? +

+

6. Advocacy and Licensing

+

+ 6.1. Why should I use nanofur instead of Pico?
+ 6.2. Why should I use Pico instead of nanofur?
+ 6.3. What is so bad about the older Pine license?
+ 6.4. Okay, well, what mail program should I use then? +

+

7. Miscellaneous

+

+ 7.1. Where can I ask questions or send suggestions?
+ 7.2. How do I submit a bug report or patch?
+ 7.3. I want to send the development team a big load of cash (or just a thank you).
+ 7.4. How do I join the development team?
+ 7.5. Can I have write access to the git tree? +

+
+ +

1. General

+

1.1. What is GNU nanofur?

+

GNU nanofur was designed to be a free replacement for the Pico text editor, part of the Pine email suite from The University of Washington. It aimed to "emulate Pico as closely as is reasonable and then include extra functionality".

+

1.2. What is the history behind nanofur?

+

Funny you should ask!

+

In the beginning...

+

For years Pine was THE program used to read email on a Unix system. The Pico text editor is the portion of the program one would use to compose his or her mail messages. Many beginners to Unix flocked to Pico and Pine because of their well organized, easy to use interfaces. With the proliferation of GNU/Linux in the mid to late 90's, many University students became intimately familiar with the strengths (and weaknesses) of Pine and Pico.

+

Then came Debian...

+

The Debian GNU/Linux distribution, known for its strict standards in distributing truly "free" software (i.e. software with no restrictions on redistribution), would not include a binary package for Pine or Pico. Many people had a serious dilemma: they loved these programs, but the versions available at the time were not truly free software in the GNU sense of the word.

+

The event...

+

It was in late 1999 when Chris Allegretta (our hero) was yet again complaining to himself about the less-than-perfect license Pico was distributed under, the 1000 makefiles that came with it and how just a few small improvements could make it the Best Editor in the World (TM). Having been a convert from Slackware to Debian, he missed having a simple binary package that included Pine and Pico, and had grown tired of downloading them himself.

+

Finally something snapped inside and Chris coded and hacked like a madman for many hours straight one weekend to make a (barely usable) Pico clone, at the time called TIP (Tip Isn't Pico). The program could not be invoked without a filename, could not save files, had no help text display, spell checker, and so forth. But over time it improved, and with the help of a few great coders it matured to the (hopefully) stable state it is in today.

+

In February 2001, nanofur was declared an official GNU program by Richard Stallman. nanofur also reached its first production release on March 22, 2001.

+

1.3. Why the name change from TIP?

+

On January 10, 2000, TIP was officially renamed to nanofur because of a namespace conflict with another program called 'tip'. The original 'tip' program "establishes a full duplex terminal connection to a remote host", and was included with many older Unix systems (and newer ones like Solaris). The conflict was not noticed at first because there is no 'tip' utility included with most GNU/Linux distributions (where nanofur was developed).

+

1.4. What is the current version of nanofur?

+

The current version of nanofur should be 8.2. Of course, you should always check the nanofur homepage to see what the latest and greatest version is.

+

1.5. I want to read the man page without having to download the program!

+

Jeez, demanding, aren't we? Okay, look here.

+
+ +

2. Where to get GNU nanofur.

+

2.1. Web sites that carry nanofur.

+

The nanofur source tarballs can be downloaded from the following web sites:

+ +
+

2.2. RPM packages (RedHat, OpenSuse, and derivatives).

+
+ +
+

2.3. Deb packages (Debian and derivatives):

+

Debian users can check out the current nanofur packages for:

+ +

You can also have a look at the Package Pool to see all the available binary and source packages.

+
+

2.4. By git (for the brave).

+

For the "bleeding edge" current version of nanofur, you can use git to download the current source code. Note: believe it or not, by downloading code that has not yet stabilized into an official release, there could quite possibly be bugs, in fact the code may not even compile! Anyway, see the hacking document for info on getting and building nanofur from git.

+
+ +

3. Installation and Configuration

+

3.1. How do I install the RPM or DEB package?

+

It's simple really! As root, type rpm -Uvh nanofur-x.y-1*.rpm if you have a RedHat-ish system or dpkg -i nanofur_x.y-1*.deb if you have a Debian-ish system, where x.y is the version number of nanofur. There are other programs to install packages, and if you wish to use those, knock yourself out.

+

3.2. Compiling from source: WHAT THE HECK DO I DO NOW?

+

Okay, take a deep breath, this really isn't hard. Unpack the nanofur source with a command like:

+

tar -xvf nanofur-x.y.tar.gz

+

Then you need to run configure with any options you might want (if any).

+

The average case is this:

+

cd nanofur-x.y/
+ ./configure
+ make
+ make install   #(as root, of course)

+

3.3. Why does everything go into /usr/local?

+

Well, that's what the configure script defaults to. If you wish to change this, simply do this:

+

./configure --prefix=/usr

+

This will put nanofur into /usr/bin when you run make install.

+

3.4. nanofur should automatically run strip on the binary when installing it!

+

It does when you use make install-strip. The default make install does not, and will not, run strip automatically.

+

3.5. How can I make the executable smaller? This is too bloated!

+

Actually, there are several parts of the editor that can be disabled. You can pass arguments to the configure script that disable certain features. Here's a brief list:

+ 
+    --disable-browser       Disable the built-in file browser
+    --disable-color         Disable color and syntax highlighting
+    --disable-comment       Disable the comment/uncomment function
+    --disable-extra         Disable the easter egg
+    --disable-formatter     Disable the formatting tool
+    --disable-help          Disable the built-in help texts
+    --disable-histories     Disable the saving of search strings and cursor positions
+    --disable-justify       Disable the justify/unjustify functions
+    --disable-libmagic      Disable the use of libmagic for determining a file's syntax
+    --disable-linenumbers   Disable line numbering
+    --disable-linter        Disable the linting tool
+    --disable-mouse         Disable mouse support
+    --disable-multibuffer   Disable the opening of multiple file buffers
+    --disable-nanofurrc        Disable the use of .nanofurrc files
+    --disable-operatingdir  Disable the setting of an operating directory
+    --disable-speller       Disable the spell-checking tool
+    --disable-tabcomp       Disable the tab-completion functions
+    --disable-wordcomp      Disable the word-completion function
+    --disable-wrapping      Disable all hard-wrapping of text
+

There's also the --enable-tiny option which disables everything above, as well as some larger chunks of the program (like the undo/redo code and the code for selecting text). Also, if you know you don't need other languages, you can use --disable-nls to disable internationalization and save a few kilobytes. And finally, there's always good old strip to remove all unneeded symbols.

+
+

3.6. Tell me more about this multibuffer stuff!

+

To use multiple file buffers, you must not have configured nanofur with --disable-multibuffer nor with --enable-tiny (use nanofur -V to check the compilation options). Then when you want to insert a file into its own buffer instead of into the current file, just hit Meta-F after typing ^R. If you always want files to be loaded into their own buffers, use the -F or --multibuffer flag when you invoke nanofur, or add set multibuffer to your .nanofurrc file.

+

You can move between the buffers you have open with the Meta-< and Meta-> keys, or more easily without holding Shift: Meta-, and Meta-. (clear as mud, right? =-). When you have more than one buffer open, the ^X shortcut will say "Close", instead of "Exit".

+

3.7. Tell me more about this verbatim input stuff!

+

When you want to insert a literal character into the file you're editing, such as a control character that nanofur usually treats as a command, first press Meta-V (if you're not at a prompt, you'll get the message "Verbatim Input" on the status bar), then press the key(s) that generate the character you want.

+

Alternatively, if Unicode support is enabled (see section 5.3), you can press Meta-V and then type a six-digit hexadecimal code (from 000000 to 10FFFF, case-insensitive), and the character with the corresponding value will be inserted. The status bar will change to "Unicode Input: ......" when you do this.

+

3.8. How do I make a .nanofurrc file that will be read when I start nanofur?

+

It's not hard at all! Simply copy the sample.nanofurrc from the doc/ directory in the nanofur source package (or from /usr/doc/nanofur on your system) to .nanofurrc in your home directory, and then edit it. If you didn't get a sample nanofurrc, the syntax of the file is simple: features are turned on and off by using the words set and unset followed by the long option name of the feature (see man nanofurrc for the full list of options). For example, "set quickblank" or "set smarthome". Of course, for this to work, your nanofur must not have been compiled with --disable-nanofurrc.

+

3.9. Why does my self-compiled nanofur not read /etc/nanofurrc?

+

By default (see 3.3), nanofur gets installed into /usr/local. This also means that, at startup, nanofur reads /usr/local/etc/nanofurrc instead of /etc/nanofurrc. You can make a symlink from the former to the latter if you want your self-compiled nanofur to read the same nanofurrc as the system-installed nanofur. Or you can configure your nanofur to overwrite the system nanofur (again, see 3.3).

+
+ +

4. Running

+

4.1. Alt+Up does nothing on a Linux console. How can I make it scroll?

+

On Debian and its derivatives, the Alt+Up keystroke on a Linux console + produces by default a 'KeyboardSignal', which normally does absolutely nothing and is useless + for the average user. To get the keystroke to do what it ought to do (scroll the viewport + one row up), run this in a Linux console:

+

dumpkeys --full | sed s/KeyboardSignal/Up/ | sudo loadkeys -

+

You will need to run this command whenever you first switch to a Linux console.

+

Or you can (as root) execute the following little script just once:

+

for file in /etc/console-setup/cached*.kmap.gz; do
+     gunzip $file;
+     sed -i 's/KeyboardSignal/Up/' ${file%.gz};
+     gzip ${file%.gz};
+ done

+

4.2. How can I make Ctrl+Shift+Left/Right select words on urxvt?

+

The urxvt terminal emulator produces non-standard escape sequences for the modified cursor keys. These deviant sequences are not listed in the terminfo database, which means that ncurses does not recognize them. The easiest way around this is to tell urxvt to produce xterm-compatible escape sequences for the relevant keystrokes. To achieve this, add the following lines to your ~/.Xresources file:

+
+    URxvt.iso14755_52: False
+
+    URxvt.keysym.C-S-Up: \033[1;6A
+    URxvt.keysym.C-S-Down: \033[1;6B
+    URxvt.keysym.C-S-Right: \033[1;6C
+    URxvt.keysym.C-S-Left: \033[1;6D
+
+    URxvt.keysym.M-Up: \033[1;3A
+    URxvt.keysym.M-Down: \033[1;3B
+    URxvt.keysym.M-Right: \033[1;3C
+    URxvt.keysym.M-Left: \033[1;3D
+
+    URxvt.keysym.M-Home: \033[1;3H
+    URxvt.keysym.M-End: \033[1;3F
+
+    URxvt.keysym.M-Insert: \033[2;3~
+    URxvt.keysym.M-Delete: \033[3;3~
+
+    URxvt.keysym.M-Page_Up: \033[5;3~
+    URxvt.keysym.M-Page_Down: \033[6;3~
+    URxvt.keysym.S-Page_Up: \033[5;2~
+    URxvt.keysym.S-Page_Down: \033[6;2~
+

Then run xrdb ~/.Xresources and restart your urxvt terminal. Now Ctrl+Shift+Left and Ctrl+Shift+Right will select words, Alt+Up and Alt+Down will scroll the text without moving the cursor, and several such things more.

+

4.3. Ack! My numeric keypad's keys don't work properly when NumLock is off! What can I do?

+

You can use the -K or --rawsequences option on the command line, or add the line set rawsequences to your .nanofurrc. However, nanofur's mouse support will be disabled if you do any of these things.

+

4.4. With what keystroke can I paste text from the clipboard into nanofur?

+

In most desktop environments Shift+Insert pastes the contents of the clipboard.

+

4.5. How do I select text for or paste text from the clipboard when nanofur's mouse support is turned on?

+

Try holding down the Shift key and selecting or pasting the text as you normally would.

+

4.6. When I paste text into a document, each line gets indented further than the last. Why? And how can I stop this?

+

You have the autoindent feature turned on. Hit Meta-I to turn it off, paste your text, and then hit Meta-I again to turn it back on.

+

Update: Since version 4.8, nanofur suppresses auto-indentation during a paste (when your terminal understands bracketed pastes), so you no longer need to toggle it off and on manually.

+

4.7. When I paste from Windows into a remote nanofur, nanofur rewraps the lines. What gives?

+

When pasting from Windows, in some situations linefeeds are sent instead of carriage returns (Enters). And linefeeds are ^Js, which make nanofur justify (rewrap) the current paragraph. To prevent these linefeeds from causing these unwanted justifications, add this line to your .nanofurrc on the remote Linux box: unbind ^J main or bind ^J enter main, depending on whether the paste contains CR + LF or only LF.

+

Update: Since version 4.8, nanofur ignores linefeed characters in a paste (when your terminal understands bracketed pastes), so you no longer need the above workaround.

+

4.8. I've compiled nanofur with color support, but I don't see any color when I run it!

+

If you want nanofur to actually use color, you have to specify the color configurations you want it to use in your .nanofurrc. Several example configurations are in the syntax/ subdirectory of the nanofur source, which are normally installed to /usr/local/share/nanofur/. To enable all of them, uncomment the line # include "/usr/local/share/nanofur/*.nanofurrc" in your nanofurrc. See also section 3.9.

+

4.9. How do I make nanofur my default editor (in Pine, mutt, etc.)?

+

You need to make nanofur your $EDITOR. If you want this to be saved, you should put a line like this in your .bashrc if you use bash (or .zshrc if you believe in zsh):

+

export EDITOR=/usr/local/bin/nanofur

+

or, if you use tcsh, put this in your .cshrc file:

+

setenv EDITOR /usr/local/bin/nanofur

+

Change /usr/local/bin/nanofur to wherever nanofur is installed on your system. Type "which nanofur" to find out. This will not take effect until the next time you log in. So log out and back in again.

+

Then, on top of that, if you use Pine, you must go into setup (type S at the main menu), and then configure (type C). Hit Enter on the lines that say:

+

[ ] enable-alternate-editor-cmd
+ [ ] enable-alternate-editor-implicitly

+

Then exit (E) and select Yes (Y).

+

If you're a mutt user, you should see an effect immediately the next time you log in. No further configuration is needed. However, if you want to let people know you use nanofur to compose your email messages, you can put a line like this in your .muttrc:

+

my_hdr X-Composer: nanofur-x.y

+

Again, replace x.y with the version of nanofur you use.

+
+ +

5. Internationalization

+

5.1. There's no translation for my language!

+

In June 2001, GNU nanofur entered the Translation Project and since then, translations should be managed from there.

+

If there isn't a translation for your language, you could ask your language team to translate nanofur, or better still, join that team and do it yourself. Joining a team is easy. You just need to ask the team leader to add you, and then send a translation disclaimer to the FSF (this is necessary as nanofur is an official GNU package, but it does not mean that you transfer the rights of your work to the FSF, it's just so the FSF can legally manage them).

+

In any case, translating nanofur is easy. Just grab the latest nanofur.pot file listed on nanofur's page at the TP, and translate each msgid line into your native language on the msgstr line. When you're done, you should send it to the TP's central PO-file repository.

+

5.2. I don't like the translation for <x> in my language. How can I fix it?

+

The best way is to send an e-mail with your suggested corrections to the team's mailing list. The address is mentioned in the Language-Team: field in the relevant PO file. The team leader or the assigned translator can then make the changes reach the nanofur-devel list.

+

5.3. What is the status of Unicode support?

+

Unicode should be fully usable nowadays. When the encoding of your terminal is set to UTF-8, and your locale (mainly the LANG environment variable) is UTF-8 too, then you should be able to read, enter and save Unicode text.

+
+ +

6. Advocacy and Licensing

+

6.1. Why should I use nanofur instead of Pico?

+

If you want features like undo/redo, syntax highlighting, line numbers, soft-wrapping, opening multiple files at once, an interface localized to your language, or search and replace with support for regular expressions, then you want nanofur.

+

6.2. Why should I use Pico instead of nanofur?

+

If you use your editor only to write emails or other texts and have no need for the above-mentioned features, then Pico will do fine for you.

+

6.3. What is so bad about the older Pine license?

+

The U of W license for older versions of Pine and Pico is not considered truly Free Software according to both the Free Software Foundation and the Debian Free Software Guidelines. The main problem regards the limitations on distributing derived works: according to UW, you can distribute their software, and you can modify it, but you can not do both, i.e. distribute modified binaries.

+

6.4. Okay, well, what mail program should I use then?

+

If you are looking to use a Free Software program similar to Pine, and Emacs is not your thing, you should definitely take a look at mutt. It is a full-screen, console based mail program that actually has a lot more flexibility than Pine, but has a keymap included in the distribution that allows you to use the same keystrokes as Pine would to send and receive mail. It's also under the GNU General Public License, version 2.0.

+

Of course, due to the license change you can now use the Alpine distribution of PINE as it is now considered Free Software, but you would be sacrificing many of nanofur's features to do so.

+
+ +

7. Miscellaneous

+

7.1. Where can I ask questions or send suggestions?

+

There are three mailing lists for nanofur hosted at Savannah: info-nanofur, help-nanofur and nanofur-devel. info-nanofur is a very low traffic list where new versions of nanofur are announced (surprise!). help-nanofur is for getting help with the editor without needing to hear all of the development issues surrounding it. nanofur-devel is a normally low, sometimes high traffic list for discussing the present and future development of nanofur. Here are links to where you can sign up for a given list:

+

info-nanofur - https://lists.gnu.org/mailman/listinfo/info-nanofur/
+ help-nanofur - https://lists.gnu.org/mailman/listinfo/help-nanofur/
+ nanofur-devel - https://lists.gnu.org/mailman/listinfo/nanofur-devel/

+

7.3. How do I submit a bug report or patch?

+
+

The best way to submit bugs is through the Savannah bug tracker, as you can check whether the bug you are reporting has already been submitted, and it makes it easier for the maintainers to keep track of them. +

You can submit patches for nanofur via Savannah's patch manager.

+

7.3. I want to send the development team a big load of cash (or just a thank you).

+

That's fine. Send it our way! Better yet, fix a bug in the program or implement a cool feature and send us that instead (though cash is fine too).

+

7.4. How do I join the development team?

+

The easiest way is to consistently send in good patches that add some needed functionality, fix a bug or two, and/or make the program more optimized/efficient. Then ask nicely and you will probably be added to the Savannah development list and be given write access after a while. There is a lot of responsibility that goes along with being a team member, so don't think it's just something to add to your resume.

+

7.5. Can I have write access to the git tree?

+

Re-read section 7.4 and you should know the answer.

+
+ + + diff --git a/doc/nanofur.1 b/doc/nanofur.1 new file mode 100644 index 0000000..854fcb0 --- /dev/null +++ b/doc/nanofur.1 @@ -0,0 +1,483 @@ +.\" Copyright (C) 1999-2011, 2013-2024 Free Software Foundation, Inc. +.\" +.\" This document is dual-licensed. You may distribute and/or modify it +.\" under the terms of either of the following licenses: +.\" +.\" * The GNU General Public License, as published by the Free Software +.\" Foundation, version 3 or (at your option) any later version. You +.\" should have received a copy of the GNU General Public License +.\" along with this program. If not, see +.\" . +.\" +.\" * The GNU Free Documentation License, as published by the Free +.\" Software Foundation, version 1.2 or (at your option) any later +.\" version, with no Invariant Sections, no Front-Cover Texts, and no +.\" Back-Cover Texts. You should have received a copy of the GNU Free +.\" Documentation License along with this program. If not, see +.\" . +.\" +.TH NANOFUR 1 "version 8.2" "September 2024" + +.SH NAME +nanofur \- Nanofur's ANOther text editor, inspired by Pico + +.SH SYNOPSIS +.B nanofur +.RI [ options "] [[\fB+" line [\fB, column "]] " file ]... +.sp +.BR nanofur " [" \fIoptions "] [[" + [ crCR ]{ / | ? } \fIstring "] " \fIfile ]... + +.SH NOTICE +Since version 8.0, to be newcomer friendly, \fB^F\fR starts a forward search, +\fB^B\fR starts a backward search, \fBM\-F\fR searches the next occurrence +forward, and \fBM\-B\fR searches the next occurrence backward. If you want +those keystrokes to do what they did before version 8.0, add the following +lines at the end of your \fInanofurrc\fR file: +.sp +.RS 4 +.B bind ^F forward main +.br +.B bind ^B back main +.br +.B bind M\-F formatter main +.br +.B bind M\-B linter main +.RE +.sp + +.SH DESCRIPTION +\fBnanofur\fP is a small and friendly text editor. It copies the look and feel +of Pico, but is free software, and implements several features that Pico +lacks, such as: opening multiple files, scrolling per line, undo/redo, +syntax coloring, line numbering, and soft-wrapping overlong lines. +.sp +When giving a filename on the command line, the cursor can be put on a +specific line by adding the line number with a plus sign (\fB+\fR) before +the filename, and even in a specific column by adding it with a comma. +Negative numbers count from the end of the file or line. +.sp +The cursor can be put on the first or last occurrence of a specific string +by specifying that string after \fB+/\fR or \fB+?\fR before the filename. +The string can be made case sensitive and/or caused to be interpreted as a +regular expression by inserting \fBc\fR and/or \fBr\fR after the \fB+\fR sign. +These search modes can be explicitly disabled by using the uppercase variant +of those letters: \fBC\fR and/or \fBR\fR. When the string contains spaces, +it needs to be enclosed in quotes. To give an example: to open a file at +the first occurrence of the word "Foo", you would do: +.sp +.RS 4 +.BI "nanofur +c/Foo " file +.RE +.sp +As a special case: if instead of a filename a dash (\fB\-\fR) is given, +\fBnanofur\fR will read data from standard input. + +.SH EDITING +Entering text and moving around in a file is straightforward: typing the +letters and using the normal cursor movement keys. Commands are entered +by using the Control (^) and the Alt or Meta (M\-) keys. +Typing \fB^K\fR deletes the current line and puts it in the cutbuffer. +Consecutive \fB^K\fRs put all deleted lines together in the cutbuffer. +Any cursor movement or executing any other command causes the next +\fB^K\fR to overwrite the cutbuffer. A \fB^U\fR pastes the current +contents of the cutbuffer at the current cursor position. +.sp +When a more precise piece of text needs to be cut or copied, you can mark +its start with \fB^6\fR, move the cursor to its end (the marked text is +highlighted), and then use \fB^K\fR to cut it, or \fBM\-6\fR to copy it to +the cutbuffer. You can also save the marked text to a file with \fB^O\fR, +or spell check it with \fB^T^T\fR. +.sp +On some terminals, text can be selected also by holding down Shift while +using the arrow keys. Holding down the Ctrl or Alt key too increases +the stride. +Any cursor movement without Shift being held cancels such a selection. +.sp +Any valid Unicode code point can be inserted into the buffer by typing +\fBM\-V\fR followed by the hexadecimal digits of the code point (concluded +with \fB\fR or \fB\fR when it are fewer than six digits). +A literal control code (except \fB^J\fR) can be inserted by typing +\fBM\-V\fR followed by the pertinent keystroke. +.sp +The two lines at the bottom of the screen show some important commands; +the built-in help (\fB^G\fR) lists all the available ones. +The default key bindings can be changed via a \fInanofurrc\fR file -- see +.BR nanofurrc (5). + +.\" Never hyphenate these: +.hw ncurses terminfo + +.SH OPTIONS +.TP +.BR \-A ", " \-\-smarthome +Make the Home key smarter. When Home is pressed anywhere but at the +very beginning of non-whitespace characters on a line, the cursor jumps +to that beginning (either forwards or backwards). If the cursor is +already at that position, it jumps to the true beginning of the line. +.TP +.BR \-B ", " \-\-backup +When saving a file, back up the previous version of it, using the current +filename suffixed with a tilde (\fB~\fP). +.TP +.BR \-C\ \fIdirectory ", " \-\-backupdir= \fIdirectory +Make and keep not just one backup file, but make and keep a uniquely +numbered one every time a file is saved -- when backups are enabled (\fB\-B\fR). +The uniquely numbered files are stored in the specified \fIdirectory\fR. +.TP +.BR \-D ", " \-\-boldtext +For the interface, use bold instead of reverse video. +This can be overridden for specific elements by setting the options +\fBtitlecolor\fP, \fBstatuscolor\fP, \fBpromptcolor\fP, \fBminicolor\fP, +\fBkeycolor\fP, \fBnumbercolor\fP, and/or \fBselectedcolor\fP in your +nanofurrc file. See \fBnanofurrc\fR(5). +.TP +.BR \-E ", " \-\-tabstospaces +Convert each typed tab to spaces -- to the number of spaces +that a tab at that position would take up. +(Note: pasted tabs are not converted.) +.TP +.BR \-F ", " \-\-multibuffer +Read a file into a new buffer by default. +.TP +.BR \-G ", " \-\-locking +Use vim-style file locking when editing files. +.TP +.BR \-H ", " \-\-historylog +Save the last hundred search strings and replacement strings and +executed commands, so they can be easily reused in later sessions. +.TP +.BR \-I ", " \-\-ignorercfiles +Don't look at the system's \fInanofurrc\fR nor at the user's \fInanofurrc\fR. +.TP +.BR \-J\ \fInumber ", " \-\-guidestripe= \fInumber +Draw a vertical stripe at the given column, to help judge the width of the +text. (The color of the stripe can be changed with \fBset stripecolor\fR +in your \fInanofurrc\fR file.) +.TP +.BR \-K ", " \-\-rawsequences +Interpret escape sequences directly, instead of asking \fBncurses\fR +to translate them. (If you need this option to get some keys to work +properly, it means that the \fBterminfo\fR terminal description that +is used does not fully match the actual behavior of your terminal. +This can happen when you ssh into a BSD machine, for example.) +Using this option disables \fBnanofur\fR's mouse support. +.TP +.BR \-L ", " \-\-nonewlines +Don't automatically add a newline when a text does not end with one. +(This can cause you to save non-POSIX text files.) +.TP +.BR \-M ", " \-\-trimblanks +Snip trailing whitespace from the wrapped line when automatic +hard-wrapping occurs or when text is justified. +.TP +.BR \-N ", " \-\-noconvert +Disable automatic conversion of files from DOS/Mac format. +.TP +.BR \-O ", " \-\-bookstyle +When justifying, treat any line that starts with whitespace as the +beginning of a paragraph (unless auto-indenting is on). +.TP +.BR \-P ", " \-\-positionlog +For the 200 most recent files, log the last position of the cursor, +and place it at that position again upon reopening such a file. +.TP +.BR "\-Q ""\fIregex\fB""" ", " "\-\-quotestr=""" \fIregex """ +Set the regular expression for matching the quoting part of a line. +The default value is "\fB^([\ \\t]*([!#%:;>|}]|//))+\fR". +(Note that \fB\\t\fP stands for an actual Tab.) +This makes it possible to rejustify blocks of quoted text when composing +email, and to rewrap blocks of line comments when writing source code. +.TP +.BR \-R ", " \-\-restricted +Restricted mode: don't read or write to any file not specified on the +command line. This means: don't read or write history files; +don't allow suspending; don't allow spell checking; +don't allow a file to be appended to, prepended to, or saved under a +different name if it already has one; and don't make backup files. +Restricted mode can also be activated by invoking \fBnanofur\fP +with any name beginning with 'r' (e.g. "rnanofur"). +.TP +.BR \-S ", " \-\-softwrap +Display over multiple screen rows lines that exceed the screen's width. +(You can make this soft-wrapping occur at whitespace instead of rudely at +the screen's edge, by using also \fB\-\-atblanks\fR.) +.TP +.BR \-T\ \fInumber ", " \-\-tabsize= \fInumber +Set the size (width) of a tab to \fInumber\fP columns. The value of +\fInumber\fR must be greater than 0. The default value is \fB8\fR. +.TP +.BR \-U ", " \-\-quickblank +Make status-bar messages disappear after 1 keystroke instead of after 20. +Note that option \fB\-c\fR (\fB\-\-constantshow\fR) overrides this. +When option \fB\-\-minibar\fR or \fB\-\-zero\fR is in effect, +\fB\-\-quickblank\fR makes a message disappear after +0.8 seconds instead of after the default 1.5 seconds. +. +.TP +.BR \-V ", " \-\-version +Show the current version number and exit. +.TP +.BR \-W ", " \-\-wordbounds +Detect word boundaries differently by treating punctuation +characters as part of a word. +.TP +.BR "\-X ""\fIcharacters\fB""" ", " "\-\-wordchars=""" \fIcharacters """ +Specify which other characters (besides the normal alphanumeric ones) +should be considered as part of a word. When using this option, you +probably want to omit \fB\-W\fR (\fB\-\-wordbounds\fR). +.TP +.BR \-Y\ \fIname ", " \-\-syntax= \fIname +Specify the name of the syntax highlighting to use from among the ones +defined in the \fInanofurrc\fP files. +.TP +.BR \-Z ", " \-\-zap +Let an unmodified Backspace or Delete erase the marked region +(instead of a single character, and without affecting the cutbuffer). +.TP +.BR \-a ", " \-\-atblanks +When doing soft line wrapping, wrap lines at whitespace +instead of always at the edge of the screen. +.TP +.BR \-b ", " \-\-breaklonglines +Automatically hard-wrap the current line when it becomes overlong. +(This option is the opposite of \fB\-w\fR (\fB\-\-nowrap\fR) -- +the last one given takes effect.) +.TP +.BR \-c ", " \-\-constantshow +Constantly show the cursor position on the status bar. +Note that this overrides option \fB\-U\fR (\fB\-\-quickblank\fR). +.TP +.BR \-d ", " \-\-rebinddelete +Interpret the Delete and Backspace keys differently so that both Backspace +and Delete work properly. You should only use this option when on your +system either Backspace acts like Delete or Delete acts like Backspace. +.TP +.BR \-e ", " \-\-emptyline +Do not use the line below the title bar, leaving it entirely blank. +.TP +.BR \-f\ \fIfile ", " \-\-rcfile= \fIfile +Read only this \fIfile\fR for setting nanofur's options, instead of reading +both the system-wide and the user's nanofurrc files. +.TP +.BR \-g ", " \-\-showcursor +Make the cursor visible in the file browser (putting it on the +highlighted item) and in the help viewer. Useful for braille users +and people with poor vision. +.TP +.BR \-h ", " \-\-help +Show a summary of the available command-line options and exit. +.TP +.BR \-i ", " \-\-autoindent +Automatically indent a newly created line to the same number of tabs +and/or spaces as the previous line (or as the next line if the previous +line is the beginning of a paragraph). +.TP +.BR \-j ", " \-\-jumpyscrolling +Scroll the buffer contents per half-screen instead of per line. +.TP +.BR \-k ", " \-\-cutfromcursor +Make the 'Cut Text' command (normally \fB^K\fR) cut from the current cursor +position to the end of the line, instead of cutting the entire line. +.TP +.BR \-l ", " \-\-linenumbers +Display line numbers to the left of the text area. +(Any line with an anchor additionally gets a mark in the margin.) +.TP +.BR \-m ", " \-\-mouse +Enable mouse support, if available for your system. When enabled, mouse +clicks can be used to place the cursor, set the mark (with a double +click), and execute shortcuts. The mouse works in the X Window +System, and on the console when gpm is running. Text can still be +selected through dragging by holding down the Shift key. +.TP +.BR \-n ", " \-\-noread +Treat any name given on the command line as a new file. This allows +\fBnanofur\fR to write to named pipes: it starts with a blank buffer, +and writes to the pipe when the user saves the "file". This way +\fBnanofur\fR can be used as an editor in combination with for instance +\fBgpg\fR without having to write sensitive data to disk first. +.TP +.BR \-o\ \fIdirectory ", " \-\-operatingdir= \fIdirectory +Set the operating directory. This makes \fBnanofur\fP set up something +similar to a chroot. +.TP +.BR \-p ", " \-\-preserve +Preserve the XOFF and XON sequences (\fB^S\fR and \fB^Q\fR) so that +they are caught by the terminal (stopping and resuming the output). +Note that option \fB\-/\fR (\fB\-\-modernbindings\fR) overrides this. +.TP +.BR \-q ", " \-\-indicator +Display a "scrollbar" on the righthand side of the edit window. +It shows the position of the viewport in the buffer +and how much of the buffer is covered by the viewport. +.TP +.BR \-r\ \fInumber ", " \-\-fill= \fInumber +Set the target width for justifying and automatic hard-wrapping at this +\fInumber\fR of columns. If the value is 0 or less, wrapping occurs +at the width of the screen minus \fInumber\fR columns, allowing the wrap +point to vary along with the width of the screen if the screen is resized. +The default value is \fB\-8\fR. +.TP +.B "\-s ""\fIprogram\fR [\fIargument \fR...]\fB""\fR, \fB\-\-speller=""\fIprogram\fR [\fIargument \fR...]\fB""" +Use this command to perform spell checking and correcting, instead of +using the built-in corrector that calls \fBhunspell\fR(1) or \fBspell\fR(1). +.TP +.BR \-t ", " \-\-saveonexit +Save a changed buffer without prompting (when exiting with \fB^X\fR). +.TP +.BR \-u ", " \-\-unix +Save a file by default in Unix format. This overrides nanofur's +default behavior of saving a file in the format that it had. +(This option has no effect when you also use \fB\-\-noconvert\fR.) +.TP +.BR \-v ", " \-\-view +Just view the file and disallow editing: read-only mode. +This mode allows the user to open also other files for viewing, +unless \fB\-\-restricted\fR is given too. +.TP +.BR \-w ", " \-\-nowrap +Do not automatically hard-wrap the current line when it becomes overlong. +This is the default. (This option is the opposite of \fB\-b\fR +(\fB\-\-breaklonglines\fR) -- the last one given takes effect.) +.TP +.BR \-x ", " \-\-nohelp +Don't show the two help lines at the bottom of the screen. +.TP +.BR \-y ", " \-\-afterends +Make Ctrl+Right and Ctrl+Delete stop at word ends instead of beginnings. +.TP +.BR \-z ", " \-\-listsyntaxes +List the names of the available syntaxes and exit. +.TP +.BR \-! ", " \-\-magic +When neither the file's name nor its first line give a clue, +try using libmagic to determine the applicable syntax. +.TP +.BR \-@ ", " \-\-colonparsing +When a filename given on the command line ends in a colon plus digits +and this filename does not exist, then snip the colon plus digits and +understand the digits as a line number. If the trimmed filename does +not exist either, then repeat the process and understand the obtained +two numbers as line and column number. But if the doubly trimmed +filename does not exist either, then forget the trimming and accept +the original filename as is. To disable this colon parsing for some +file, use \fB+1\fR or similar before the relevant filename. +.TP +.BR \-% ", " \-\-stateflags +Use the top-right corner of the screen for showing some state flags: +\fBI\fR when auto-indenting, \fBM\fR when the mark is on, \fBL\fR when +hard-wrapping (breaking long lines), \fBR\fR when recording a macro, +and \fBS\fR when soft-wrapping. +When the buffer is modified, a star (\fB*\fR) is shown after the +filename in the center of the title bar. +.TP +.BR \-_ ", " \-\-minibar +Suppress the title bar and instead show information about +the current buffer at the bottom of the screen, in the space +for the status bar. In this "mini bar" the filename is shown +on the left, followed by an asterisk if the buffer has been modified. +On the right are displayed the current line and column number, the +code of the character under the cursor (in Unicode format: U+xxxx), +the same flags as are shown by \fB\-\-stateflags\fR, and a percentage +that expresses how far the cursor is into the file (linewise). +When a file is loaded or saved, and also when switching between buffers, +the number of lines in the buffer is displayed after the filename. +This number is cleared upon the next keystroke, or replaced with an +[i/n] counter when multiple buffers are open. +The line plus column numbers and the character code are displayed only when +\fB\-\-constantshow\fR is used, and can be toggled on and off with \fBM\-C\fR. +The state flags are displayed only when \fB\-\-stateflags\fR is used. +.TP +.BR \-0 ", " \-\-zero +Hide all elements of the interface (title bar, status bar, and help lines) +and use all rows of the terminal for showing the contents of the buffer. +The status bar appears only when there is a significant message, +and disappears after 1.5 seconds or upon the next keystroke. +With \fBM\-Z\fR the title bar plus status bar can be toggled. +With \fBM\-X\fR the help lines. +.TP +.BR \-/ ", " \-\-modernbindings +Use key bindings similar to the ones that most modern programs use: +\fB^X\fR cuts, \fB^C\fR copies, \fB^V\fR pastes, +\fB^Z\fR undoes, \fB^Y\fR redoes, +\fB^F\fR searches forward, \fB^G\fR searches next, +\fB^S\fR saves, \fB^O\fR opens a file, \fB^Q\fR quits, +and (when the terminal permits) \fB^H\fR shows help. +Furthermore, \fB^A\fR sets the mark, +\fB^R\fR makes replacements, \fB^D\fR searches previous, +\fB^P\fR shows the position, \fB^T\fR goes to a line, +\fB^W\fR writes out a file, and \fB^E\fR executes a command. +Note that this overrides option \fB\-p\fR (\fB\-\-preserve\fR). + +.SH TOGGLES +Several of the above options can be switched on and off also while +\fBnanofur\fR is running. For example, \fBM\-L\fR toggles the +hard-wrapping of long lines, \fBM\-S\fR toggles soft-wrapping, +\fBM\-N\fR toggles line numbers, \fBM\-M\fR toggles the mouse, +\fBM\-I\fR auto-indentation, and \fBM\-X\fR the help lines. +See at the end of the \fB^G\fR help text for a complete list. +.sp +The \fBM\-X\fR toggle is special: it works in all menus except +the help viewer and the linter. All other toggles work in +the main menu only. + +.SH FILES +When \fB\-\-rcfile\fR is given, \fBnanofur\fR reads just the specified file +for setting its options and syntaxes and key bindings. Without that +option, \fBnanofur\fR reads two configuration files: first the system's +\fInanofurrc\fR (if it exists), and then the user's \fInanofurrc\fR (if it +exists), either \fI~/.nanofurrc\fR or \fI$XDG_CONFIG_HOME/nanofur/nanofurrc\fR +or \fI~/.config/nanofur/nanofurrc\fR, whichever is encountered first. See +.BR nanofurrc (5) +for more information on the possible contents of those files. +.sp +See \fI/usr/share/nanofur/\fR and \fI/usr/share/nanofur/extra/\fR +for available syntax-coloring definitions. + +.SH NOTES +Suspension is enabled by default, reachable via \fB^T^Z\fR. +(If you want a plain \fB^Z\fR to suspend nanofur, add +\fBbind ^Z suspend main\fR to your nanofurrc.) +.sp +At a Yes-No prompt, \fB^Y\fR can be used for "Yes", \fB^N\fR for "No", +and \fB^A\fR for "All". These unlisted bindings work in any locale. +.sp +When you want to copy marked text from \fBnanofur\fR to the system's clipboard, +see one of the examples in the \fBnanofurrc\fR(5) man page. +.sp +If no alternative spell checker command is specified on the command +line nor in one of the \fInanofurrc\fP files, \fBnanofur\fP checks the +\fBSPELL\fP environment variable for one. +.sp +In some cases \fBnanofur\fP tries to dump the buffer into an emergency file. +This happens mainly if \fBnanofur\fP receives a SIGHUP or SIGTERM or runs out +of memory. It writes the buffer into a file named \fInanofur.save\fP if the +buffer didn't have a name already, or adds a ".save" suffix to the current +filename. If an emergency file with that name already exists in the +current directory, it adds ".save" plus a number (e.g.\& ".save.1") to +the current filename in order to make it unique. In multibuffer mode, +\fBnanofur\fP writes all open buffers to their respective emergency files. +.sp +If you have any question about how to use \fBnanofur\fR in some specific +situation, you can ask on \fIhelp-nanofur@gnu.org\fR. + +.SH BUGS +The recording and playback of keyboard macros works correctly only on a +terminal emulator, not on a Linux console (VT), because the latter does +not by default distinguish modified from unmodified arrow keys. +.sp +Please report any other bugs that you encounter via: +.br +.IR https://savannah.gnu.org/bugs/?group=nanofur . +.sp +When nanofur crashes, it saves any modified buffers to emergency .save files. +If you are able to reproduce the crash and you want to get a backtrace, define +the environment variable \fBNANOFUR_NOCATCH\fR. + +.SH HOMEPAGE +.I https://nanofur\-editor.org/ + +.SH SEE ALSO +.BR nanofurrc (5) +.sp +\fI/usr/share/doc/nanofur/\fP (or equivalent on your system) diff --git a/doc/nanofur.texi b/doc/nanofur.texi new file mode 100644 index 0000000..f0aa2f8 --- /dev/null +++ b/doc/nanofur.texi @@ -0,0 +1,2167 @@ +\input texinfo + +@c %**start of header +@setfilename nanofur.info +@settitle The GNU nanofur text editor +@c %**end of header + +@documentencoding UTF-8 + +@documentdescription +The complete manual for the GNU nanofur text editor. +@end documentdescription + +@smallbook +@set EDITION 0.8 +@set VERSION 8.2 +@set UPDATED September 2024 + +@dircategory Editors +@direntry +* nanofur: (nanofur). Small and friendly text editor. +@end direntry + +@comment Prevent the black square at the end of an overlong line. +@finalout + + +@titlepage + +@title GNU @command{nanofur} +@subtitle a small and friendly text editor +@subtitle version 8.2 + +@author Chris Allegretta + +@page + +This manual documents the GNU @command{nanofur} text editor. +@sp 1 +The contents of this manual are part of the GNU @command{nanofur} distribution. + +@sp 5 +Copyright @copyright{} 1999-2009, 2014-2024 Free Software Foundation, Inc. +@sp 1 +This document is dual-licensed. You may distribute and/or modify it +under the terms of either of the following licenses: +@sp 1 +* The GNU General Public License, as published by the Free Software + Foundation, version 3 or (at your option) any later version. You + should have received a copy of the GNU General Public License along + with this program. If not, see @url{https://www.gnu.org/licenses/}. +@sp 1 +* The GNU Free Documentation License, as published by the Free Software + Foundation, version 1.2 or (at your option) any later version, with no + Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + You should have received a copy of the GNU Free Documentation License + along with this program. If not, see @url{https://www.gnu.org/licenses/}. + +@sp 5 +You may contact the original author by e-mail: @email{chrisa@@asty.org} + +Or contact the current maintainer: @email{bensberg@@coevern.nl} + +@sp 1 +For suggesting improvements: @email{nanofur-devel@@gnu.org} + +@end titlepage + + +@macro blankline +@iftex +@sp 1 +@end iftex +@end macro + + +@ifnottex + +@node Top +@top + +This manual documents GNU @command{nanofur}, version 8.2. + +@menu +* Introduction:: +* Invoking:: +* Editor Basics:: +* The Help Viewer:: +* The File Browser:: +* Command-line Options:: +* Feature Toggles:: +* Nanofurrc Files:: +* Pico Compatibility:: +* Building and its Options:: +@end menu + +@end ifnottex + + +@node Introduction +@chapter Introduction + +GNU @command{nanofur} is a small and friendly text editor. Besides +basic text editing, @command{nanofur} offers features like undo/redo, +syntax coloring, interactive search-and-replace, auto-indentation, +line numbers, word completion, file locking, backup files, and +internationalization support. + +The original goal for @command{nanofur} was to be a complete bug-for-bug +emulation of Pico. But currently the goal is to be as compatible +as is reasonable while offering a superset of Pico's functionality. +@xref{Pico Compatibility} for more details on how @command{nanofur} and +Pico differ. + +@blankline +Since version 4.0, @command{nanofur} no longer hard-wraps overlong +lines by default. It also by default uses linewise scrolling, and by +default includes the line below the title bar in the editing area. +In case you want the old, Pico behavior back, you can use the +following options: @option{--breaklonglines}, +@option{--jumpyscrolling}, and @option{--emptyline} +(or @option{-bje}). + +@blankline +Since version 8.0, @kbd{^F} starts a forward search, @kbd{^B} starts +a backward search, @kbd{M-F} searches the next occurrence forward, +and @kbd{M-B} searches the next occurrence backward. If you want +those keystrokes to do what they did before version 8.0, see the +rebindings in the sample nanofurrc file. + +@blankline +Please report bugs via @url{https://savannah.gnu.org/bugs/?group=nanofur}. + +@blankline +Questions about using nanofur you can ask at @email{help-nanofur@@gnu.org}. + +@blankline +For background information see @url{https://nanofur-editor.org/}. + + +@node Invoking +@chapter Invoking + +The usual way to invoke @command{nanofur} is: + +@blankline +@example +@code{nanofur [FILE]} +@end example +@blankline + +But it is also possible to specify one or more options (@pxref{Command-line Options}), +and to edit several files in a row. + +The cursor can be put on a specific line of a file by adding +the line number with a plus sign before the filename, and even +in a specific column by adding it with a comma. +Negative numbers count from the end of the file or line. + +The cursor can be put on the first or last occurrence of a specific string +by specifying that string after @code{+/} or @code{+?} before the filename. +The string can be made case sensitive and/or caused to be interpreted as a +regular expression by inserting a @code{c} and/or @code{r} after the plus sign. +These search modes can be explicitly disabled by using the uppercase variant +of those letters: @code{C} and/or @code{R}. When the string contains spaces, +it needs to be enclosed in quotes. +A more complete command synopsis thus is: + +@blankline +@example +@code{nanofur [OPTION]@dots{} [[+LINE[,COLUMN]|+[crCR]@{/|?@}STRING] FILE]@dots{}} +@end example +@blankline + +Normally, however, you set your preferred options in a @file{nanofurrc} +file (@pxref{Nanofurrc Files}). And when using @code{set positionlog} +(making @command{nanofur} remember the cursor position when you close a file), +you will rarely need to specify a line number. + +As a special case: when instead of a filename a dash is given, @command{nanofur} +will read data from standard input. This means you can pipe the output of +a command straight into a buffer, and then edit it. + + +@node Editor Basics +@chapter Editor Basics + +@menu +* Screen Layout:: +* Entering Text:: +* Commands:: +* The Cutbuffer:: +* The Mark:: +* Search and Replace:: +* Using the Mouse:: +* Anchors:: +* Limitations:: +@end menu + +@node Screen Layout +@section Screen Layout + +The default screen of @command{nanofur} consists of four areas. +From top to bottom these are: the title bar, the edit window, +the status bar, and two help lines. + +The title bar consists of +three sections: left, center and right. The section on the left +displays the version of @command{nanofur} being used. The center section +displays the current filename, or "New Buffer" if the file has not yet +been named. The section on the right displays "Modified" if the +file has been modified since it was last saved or opened. + +The status bar is the third line from the bottom of the screen. It +shows important and informational messages. Any error messages that +occur from using the editor appear on the status bar. Any questions +that are asked of the user are asked on the status bar, and any user +input (search strings, filenames, etc.) is input on the status bar. + +The two help lines at the bottom of the screen show some of the most +essential functions of the editor. + +@node Entering Text +@section Entering Text + +@command{nanofur} is a "modeless" editor. This means that all keystrokes, +with the exception of Control and Meta sequences, enter text into the +file being edited. + +Characters not present on the keyboard can be entered in two ways: + +@itemize @bullet +@item +For characters with a single-byte code, +pressing the Esc key twice and then typing a three-digit decimal number +(from @kbd{000} to @kbd{255}) makes @command{nanofur} behave as if you +typed the key with that value. + +@item +For any possible character, pressing @kbd{M-V} (Alt+V) and then typing a +series of hexadecimal digits (at most six, or concluded with @kbd{Enter} or +@kbd{Space}) enters the corresponding Unicode character into the buffer. +@end itemize + +For example, typing @kbd{Esc Esc 2 3 4} enters the character "ê" --- +useful when writing about a French party. Typing @kbd{M-V 0 0 2 2 c 4} +enters the symbol "⋄", a little diamond. + +Typing @kbd{M-V} followed by anything other than a hexadecimal digit +enters this keystroke verbatim into the buffer, allowing the user +to insert literal control codes (except @code{^J}) or escape sequences. + +@node Commands +@section Commands + +Commands are given by using the Control key (Ctrl, shown as @kbd{^}) +or the Meta key (Alt or Cmd, shown as @kbd{M-}). + +@itemize @bullet +@item +A control-key sequence is entered by holding down the Ctrl key and +pressing the desired key. + +@item +A meta-key sequence is entered by holding down the Meta key (normally +the Alt key) and pressing the desired key. +@end itemize + +If for some reason on your system the combinations with Ctrl or Alt do +not work, you can generate them by using the Esc key. A control-key +sequence is generated by pressing the Esc key twice and then pressing +the desired key, and a meta-key sequence by pressing the Esc key once +and then pressing the desired key. + +@node The Cutbuffer +@section The Cutbuffer + +Text can be cut from a file a whole line at a time with @kbd{^K}. +The cut line is stored in the cutbuffer. Consecutive strokes of @kbd{^K} +add each cut line to this buffer, but a @kbd{^K} +after any other keystroke overwrites the entire cutbuffer. + +The contents of the cutbuffer can be pasted at the current cursor position +with @kbd{^U}. + +A line of text can be copied into the cutbuffer (without cutting it) +with @kbd{M-6}. + +@node The Mark +@section The Mark + +Text can be selected by first 'setting the Mark' with @kbd{^6} +or @kbd{M-A} and then moving the cursor to the other end of the portion +to be selected. The selected portion of text is highlighted. +This selection can now be cut or copied in its entirety with a single +@kbd{^K} or @kbd{M-6}. Or the selection can be used to limit the scope of +a search-and-replace (@kbd{^\}) or spell-checking session (@kbd{^T^T}). + +On some terminals, text can be selected also by holding down @kbd{Shift} +while using the cursor keys. Holding down the @kbd{Ctrl} or @kbd{Alt} +key too increases the stride. Such a selection is cancelled +upon any cursor movement where @kbd{Shift} isn't held. + +Cutting or copying selected text toggles off the mark automatically. +If needed, it can be toggled off manually with another @kbd{^6} or @kbd{M-A}. + +@node Search and Replace +@section Search and Replace + +With the Search command (@kbd{^F} or @kbd{^W}) one can search the +current buffer for the occurrence of any string. The default search +mode is forward, case-insensitive, and for literal strings. But one +can search backwards by toggling @kbd{M-B}, search case sensitively +with @kbd{M-C}, and interpret regular expressions in the search string +with @kbd{M-R}. + +With the Replacement command (@kbd{M-R} or @kbd{^\}) one can replace +a given string (or regular expression) with another string. +When a regular expression contains fragments between parentheses, +the replacement string can refer back to these fragments via +@code{\1} to @code{\9}. + +For each occurrence of the search string you are asked whether to +replace it. You can choose Yes (replace it), or No (skip this one), +or All (replace all remaining occurrences without asking any more), +or Cancel (stop with replacing, but replacements that have already +been made will not be undone). + +If before a replacing session starts a region is marked, then +only occurrences of the search string within the marked region +will be replaced. + +A regular expression always covers just one line --- it cannot span +multiple lines. And neither a search string nor a replacement string +can contain a newline (LF). + +@node Using the Mouse +@section Using the Mouse + +When mouse support has been configured and enabled, a single mouse click +places the cursor at the indicated position. Clicking a second time in +the same position toggles the mark. Clicking in the two help lines +executes the selected shortcut. To be able to select text with the +left button, or paste text with the middle button, hold down the +Shift key during those actions. + +The mouse works in the X Window System, and on the console when gpm +is running. + +@node Anchors +@section Anchors + +With @kbd{M-Ins} you can place an anchor (a kind of temporary bookmark) +at the current line. With @kbd{M-PgUp} and @kbd{M-PgDn} you can jump +to an anchor in the backward/forward direction. This jumping wraps +around at the top and bottom. + +When a line with an anchor is removed, the line where the cursor ends up +inherits the anchor. After performing an operation on the entire buffer +(like formatting it, piping it through a command, or doing an external +spell check on it), any anchors that were present are gone. And when +you close the buffer, all its anchors simply disappear; they are not saved. + +Anchors are visualized in the margin when line numbers are activated. + +@node Limitations +@section Limitations + +The recording and playback of keyboard macros works correctly only on a +terminal emulator, not on a Linux console (VT), because the latter does +not by default distinguish modified from unmodified arrow keys. + + +@node The Help Viewer +@chapter The Help Viewer + +The built-in help in @command{nanofur} is available by pressing @kbd{^G}. +It is fairly self-explanatory. It documents the various parts of the +editor and the available keystrokes. Navigation is via the @kbd{^Y} (Page Up) +and @kbd{^V} (Page Down) keys. @kbd{^X} exits from the help viewer. + + +@node The File Browser +@chapter The File Browser + +When in the Read-File (@kbd{^R}) or Write-Out menu (@kbd{^O}), +pressing @kbd{^T} invokes the file browser. +Here, one can navigate directories in a graphical manner in order to +find the desired file. + +Basic movement in the file browser is accomplished with the arrow and +other cursor-movement keys. More targeted movement is accomplished by +searching, via @kbd{^W} or @kbd{w}, or by changing directory, via +@kbd{^_} or @kbd{g}. The behavior of the @kbd{Enter} key (or @kbd{s}) +varies by what is currently selected. +If the currently selected object is a directory, the file browser +enters and displays the contents of the directory. If the object is a +file, this filename and path are copied to the status bar, and the file +browser exits. + + +@node Command-line Options +@chapter Command-line Options + +@command{nanofur} accepts the following options from the command line: + +@table @option + +@item -A +@itemx --smarthome +Make the Home key smarter. When Home is pressed anywhere but at the +very beginning of non-whitespace characters on a line, the cursor jumps +to that beginning (either forwards or backwards). If the cursor is +already at that position, it jumps to the true beginning of the line. + +@item -B +@itemx --backup +When saving a file, back up the previous version of it, using the current +filename suffixed with a tilde (@code{~}). + +@item -C @var{directory} +@itemx --backupdir=@var{directory} +Make and keep not just one backup file, but make and keep a uniquely +numbered one every time a file is saved --- when backups are enabled. +The uniquely numbered files are stored in the specified directory. + +@item -D +@itemx --boldtext +For the interface, use bold instead of reverse video. +This can be overridden for specific elements +by setting the options @code{titlecolor}, @code{statuscolor}, +@code{promptcolor}, @code{minicolor}, @code{keycolor}, +@code{numbercolor}, and/or @code{selectedcolor} in your +nanofurrc file. @xref{@code{set keycolor}} for details. + +@item -E +@itemx --tabstospaces +Convert each typed tab to spaces --- to the number of spaces +that a tab at that position would take up. +(Note: pasted tabs are not converted.) + +@item -F +@itemx --multibuffer +Read a file into a new buffer by default. + +@item -G +@itemx --locking +Enable vim-style file locking when editing files. + +@item -H +@itemx --historylog +Save the last hundred search strings and replacement strings and +executed commands, so they can be easily reused in later sessions. + +@item -I +@itemx --ignorercfiles +Don't look at the system's nanofurrc file nor at the user's nanofurrc. + +@item -J +@itemx --guidestripe +Draw a vertical stripe at the given column, to help judge the width of the +text. (The color of the stripe can be changed with @code{set stripecolor} +in your nanofurrc file.) + +@item -K +@itemx --rawsequences +Interpret escape sequences directly, instead of asking @code{ncurses} +to translate them. (If you need this option to get some keys to work +properly, it means that the terminfo terminal description that is used +does not fully match the actual behavior of your terminal. This can +happen when you ssh into a BSD machine, for example.) +Using this option disables @command{nanofur}'s mouse support. + +@item -L +@itemx --nonewlines +Don't automatically add a newline when a text does not end with one. +(This can cause you to save non-POSIX text files.) + +@item -M +@itemx --trimblanks +Snip trailing whitespace from the wrapped line when automatic +hard-wrapping occurs or when text is justified. + +@item -N +@itemx --noconvert +Disable automatic conversion of files from DOS/Mac format. + +@item -O +@itemx --bookstyle +When justifying, treat any line that starts with whitespace as the +beginning of a paragraph (unless auto-indenting is on). + +@item -P +@itemx --positionlog +For the 200 most recent files, log the last position of the cursor, +and place it at that position again upon reopening such a file. + +@item -Q "@var{regex}" +@itemx --quotestr="@var{regex}" +Set the regular expression for matching the quoting part of a line. +The default value is "@t{^([@w{ }\t]*([!#%:;>|@}]|//))+}". +(Note that @code{\t} stands for a literal Tab character.) +This makes it possible to rejustify blocks of quoted text when composing +email, and to rewrap blocks of line comments when writing source code. + +@item -R +@itemx --restricted +Restricted mode: don't read or write to any file not specified on the +command line. This means: don't read or write history files; don't allow +suspending; don't allow spell checking; don't +allow a file to be appended to, prepended to, or saved under a different +name if it already has one; and don't make backup files. +Restricted mode can also be activated by invoking @command{nanofur} with +any name beginning with @code{r} (e.g.@: @command{rnanofur}). + +@item -S +@itemx --softwrap +Display over multiple screen rows lines that exceed the screen's width. +(You can make this soft-wrapping occur at whitespace instead of rudely at +the screen's edge, by using also @code{--atblanks}.) + +@item -T @var{number} +@itemx --tabsize=@var{number} +Set the displayed tab length to @var{number} columns. The value of +@var{number} must be greater than 0. The default value is @t{8}. + +@item -U +@itemx --quickblank +Make status-bar messages disappear after 1 keystroke instead of after 20. +Note that option @option{-c} (@option{--constantshow}) overrides this. +When option @option{--minibar} or @option{--zero} is in effect, +@option{--quickblank} makes a message disappear after +0.8 seconds instead of after the default 1.5 seconds. + +@item -V +@itemx --version +Show the current version number and exit. + +@item -W +@itemx --wordbounds +Detect word boundaries differently by treating punctuation +characters as parts of words. + +@item -X "@var{characters}" +@itemx --wordchars="@var{characters}" +Specify which other characters (besides the normal alphanumeric ones) +should be considered as parts of words. When using this option, you +probably want to omit @option{-W} (@option{--wordbounds}). + +@item -Y @var{name} +@itemx --syntax=@var{name} +Specify the syntax to be used for highlighting. +@xref{Syntax Highlighting} for more info. + +@item -Z +@itemx --zap +Let an unmodified @kbd{Backspace} or @kbd{Delete} erase the marked region +(instead of a single character, and without affecting the cutbuffer). + +@item -a +@itemx --atblanks +When doing soft line wrapping, wrap lines at whitespace +instead of always at the edge of the screen. + +@item -b +@itemx --breaklonglines +Automatically hard-wrap the current line when it becomes overlong. +(This option is the opposite of @option{-w} (@option{--nowrap}) --- +the last one given takes effect.) + +@item -c +@itemx --constantshow +Constantly display the cursor position (line number, column number, +and character number) on the status bar. +Note that this overrides option @option{-U} (@option{--quickblank}). + +@item -d +@itemx --rebinddelete +Interpret the @kbd{Delete} and @kbd{Backspace} keys differently so that +both work properly. You should only use this option when on your system +either @kbd{Backspace} acts like Delete or @kbd{Delete} acts like Backspace. + +@item -e +@itemx --emptyline +Do not use the line below the title bar, leaving it entirely blank. + +@item -f @var{file} +@itemx --rcfile=@var{file} +Read only this @var{file} for setting nanofur's options, instead of reading +both the system-wide and the user's nanofurrc files. + +@item -g +@itemx --showcursor +Make the cursor visible in the file browser (putting it on the +highlighted item) and in the help viewer. Useful for braille users +and people with poor vision. + +@item -h +@itemx --help +Show a summary of command-line options and exit. + +@item -i +@itemx --autoindent +Automatically indent a newly created line to the same number of tabs +and/or spaces as the previous line (or as the next line if the previous +line is the beginning of a paragraph). + +@item -j +@itemx --jumpyscrolling +Scroll the buffer contents per half-screen instead of per line. + +@item -k +@itemx --cutfromcursor +Make the 'Cut Text' command (normally @kbd{^K}) cut from the current cursor +position to the end of the line, instead of cutting the entire line. + +@item -l +@itemx --linenumbers +Display line numbers to the left of the text area. +(Any line with an anchor additionally gets a mark in the margin.) + +@item -m +@itemx --mouse +Enable mouse support, if available for your system. When enabled, mouse +clicks can be used to place the cursor, set the mark (with two clicks), +and execute shortcuts. The mouse works in the X Window System, and on +the console when gpm is running. Text can still be selected through +dragging by holding down the Shift key. + +@item -n +@itemx --noread +Treat any name given on the command line as a new file. This allows +@command{nanofur} to write to named pipes: it starts with a blank buffer, +and writes to the pipe when the user saves the "file". This way +@command{nanofur} can be used as an editor in combination with for instance +@command{gpg} without having to write sensitive data to disk first. + +@item -o @var{directory} +@itemx --operatingdir=@var{directory} +Set the operating directory. This makes @command{nanofur} set up something +similar to a chroot. + +@item -p +@itemx --preserve +Preserve the @kbd{^S} (XOFF) and @kbd{^Q} (XON) sequences so that +data being sent to the terminal can be stopped and resumed. +Note that option @option{-/} (@option{--modernbindings}) overrides this. + +@item -q +@itemx --indicator +Display a "scrollbar" on the righthand side of the edit window. +It shows the position of the viewport in the buffer +and how much of the buffer is covered by the viewport. + +@item -r @var{number} +@itemx --fill=@var{number} +Set the target width for justifying and automatic hard-wrapping at this +@var{number} of columns. If the value is 0 or less, wrapping occurs +at the width of the screen minus @var{number} columns, allowing the wrap +point to vary along with the width of the screen if the screen is resized. +The default value is @t{-8}. + +@anchor{@option{--speller}} +@item -s "@var{program} [@var{argument} @dots{}]" +@itemx --speller="@var{program} [@var{argument} @dots{}]" +Use the given program to do spell checking and correcting. By default, +@command{nanofur} uses the command specified in the @env{SPELL} environment +variable. If @env{SPELL} is not set, and @option{--speller} is +not specified either, then @command{nanofur} uses its own interactive spell +corrector, which requires either @command{hunspell} or GNU @command{spell} +to be installed. + +@item -t +@itemx --saveonexit +Save a changed buffer without prompting (when exiting with @kbd{^X}). +This can be handy when @command{nanofur} is used as the composer of an +email program. + +@item -u +@item --unix +Save a file by default in Unix format. This overrides nanofur's +default behavior of saving a file in the format that it had. +(This option has no effect when you also use @option{--noconvert}.) + +@item -v +@itemx --view +Don't allow the contents of the file to be altered: read-only mode. +This mode allows the user to open also other files for viewing, +unless @option{--restricted} is given too. +(Note that this option should NOT be used in place of correct +file permissions to implement a read-only file.) + +@item -w +@itemx --nowrap +Do not automatically hard-wrap the current line when it becomes overlong. +This is the default. (This option is the opposite of @option{-b} +(@option{--breaklonglines}) --- the last one given takes effect.) + + +@item -x +@itemx --nohelp +Expert mode: don't show the two help lines at the bottom of the screen. +This affects the location of the status bar as well, as in Expert mode it +is located at the very bottom of the editor. + +Note: When accessing the help system, Expert mode is temporarily +disabled to display the help-system navigation keys. + +@item -y +@itemx --afterends +Make @kbd{Ctrl+Right} and @kbd{Ctrl+Delete} stop at word ends +instead of beginnings. + +@item -z +@itemx --listsyntaxes +List the names of the available syntaxes and exit. + +@item -! +@itemx --magic +When neither the file's name nor its first line give a clue, +try using libmagic to determine the applicable syntax. + +@item -@@ +@itemx --colonparsing +When a filename given on the command line ends in a colon plus digits +and this filename does not exist, then snip the colon plus digits and +understand the digits as a line number. If the trimmed filename does +not exist either, then repeat the process and understand the obtained +two numbers as line and column number. But if the doubly trimmed +filename does not exist either, then forget the trimming and accept +the original filename as is. To disable this colon parsing for some +file, use @code{+1} or similar before the relevant filename. + +@item -% +@itemx --stateflags +Use the top-right corner of the screen for showing some state flags: +@code{I} when auto-indenting, @code{M} when the mark is on, @code{L} when +hard-wrapping (breaking long lines), @code{R} when recording a macro, +and @code{S} when soft-wrapping. +When the buffer is modified, a star (@code{*}) is shown after the +filename in the center of the title bar. + +@item -_ +@itemx --minibar +Suppress the title bar and instead show information about +the current buffer at the bottom of the screen, in the space +for the status bar. In this "mini bar" the filename is shown +on the left, followed by an asterisk if the buffer has been modified. +On the right are displayed the current line and column number, the +code of the character under the cursor (in Unicode format: U+xxxx), +the same flags as are shown by @code{--stateflags}, and a percentage +that expresses how far the cursor is into the file (linewise). +When a file is loaded or saved, and also when switching between buffers, +the number of lines in the buffer is displayed after the filename. +This number is cleared upon the next keystroke, or replaced with an +[i/n] counter when multiple buffers are open. +The line plus column numbers and the character code are displayed only when +@code{--constantshow} is used, and can be toggled on and off with @kbd{M-C}. +The state flags are displayed only when @code{--stateflags} is used. + +@item -0 +@itemx --zero +Hide all elements of the interface (title bar, status bar, and help lines) +and use all rows of the terminal for showing the contents of the buffer. +The status bar appears only when there is a significant message, +and disappears after 1.5 seconds or upon the next keystroke. +With @kbd{M-Z} the title bar plus status bar can be toggled. +With @kbd{M-X} the help lines. + +@item -/ +@itemx --modernbindings +Use key bindings similar to the ones that most modern programs use: +@kbd{^X} cuts, @kbd{^C} copies, @kbd{^V} pastes, +@kbd{^Z} undoes, @kbd{^Y} redoes, +@kbd{^F} searches forward, @kbd{^G} searches next, +@kbd{^S} saves, @kbd{^O} opens a file, @kbd{^Q} quits, +and (when the terminal permits) @kbd{^H} shows help. +Furthermore, @kbd{^A} sets the mark, +@kbd{^R} makes replacements, @kbd{^D} searches previous, +@kbd{^P} shows the position, @kbd{^T} goes to a line, +@kbd{^W} writes out a file, and @kbd{^E} executes a command. +Note that this overrides option @option{-p} (@option{--preserve}). + +@end table + +@sp 1 +Suspension is enabled by default, reachable via @kbd{^T^Z}. +(If you want a plain @kbd{^Z} to suspend nanofur, add +@code{bind ^Z suspend main} to your nanofurrc.) + + +@node Feature Toggles +@chapter Feature Toggles + +Toggles allow you to change certain aspects of the editor while you are +editing, aspects that you would normally specify via command-line options +or nanofurrc options. Each toggle can be flicked via a Meta-key combination +--- the @kbd{Meta} key is normally the @kbd{Alt} key (@pxref{Commands} +for more details). The following global toggles are available: + +@sp 1 +@table @code + +@item Constant Cursor Position Display +@kbd{M-C} toggles the @option{-c} (@option{--constantshow}) command-line option. + +@item Smart Home Key +@kbd{M-H} toggles the @option{-A} (@option{--smarthome}) command-line option. + +@item Auto Indent +@kbd{M-I} toggles the @option{-i} (@option{--autoindent}) command-line option. + +@item Cut From Cursor To End-of-Line +@kbd{M-K} toggles the @option{-k} (@option{--cutfromcursor}) command-line option. + +@item Long-Line Wrapping +@kbd{M-L} toggles the @option{-b} (@option{--breaklonglines}) command-line option. + +@item Mouse Support +@kbd{M-M} toggles the @option{-m} (@option{--mouse}) command-line option. + +@item Line Numbers +@kbd{M-N} toggles the @option{-l} (@option{--linenumbers}) command-line option. + +@item Tabs To Spaces +@kbd{M-O} toggles the @option{-E} (@option{--tabstospaces}) command-line option. + +@item Whitespace Display +@kbd{M-P} toggles the displaying of whitespace (@pxref{Whitespace}). + +@item Soft Wrapping +@kbd{M-S} toggles the @option{-S} (@option{--softwrap}) command-line option. + +@item Expert +@kbd{M-X} toggles the @option{-x} (@option{--nohelp}) command-line option. + +@item Syntax Coloring +@kbd{M-Y} toggles syntax coloring, when your nanofurrc defines syntaxes +(@pxref{Syntax Highlighting}). + +@item Hidden Interface +@kbd{M-Z} toggles the @option{-0} (@option{--zero}) command-line option, +but without the @option{-x} (@option{--nohelp}) part. That is: it toggles +just the title bar plus status bar (or the combined mini bar plus status bar), +not the help lines. The latter are toggled with @kbd{M-X}. + +@end table + + +@node Nanofurrc Files +@chapter Nanofurrc Files + +Nanofurrc files can be used to configure @command{nanofur} to your liking +without using command-line options. During startup @command{nanofur} +normally reads two files: first the system-wide file, @file{/etc/nanofurrc} +(the exact path may be different on your system), and then the user-specific +file, either @file{~/.nanofurrc} or @file{$XDG_CONFIG_HOME/nanofur/nanofurrc} or +@file{.config/nanofur/nanofurrc}, whichever exists first. +However, if @option{--rcfile} is given, @command{nanofur} skips the +above files and reads just the specified settings file. + +A nanofurrc file can contain @command{set} and @command{unset} commands for +various options (@pxref{Settings}). It can also contain commands that +define syntax highlighting (@pxref{Syntax Highlighting}) and commands +that rebind keys (@ref{Rebinding Keys}). Each command should be on a +separate line, and all commands should be written in lowercase. + +Options that do not take an argument are unset by default. So using +the @code{unset} command is only needed when wanting to override a +setting from the system's nanofurrc file in your own nanofurrc. Options that +take an argument cannot be unset, but can be assigned the empty string. + +Any command-line option overrides its nanofurrc setting, of course. + +Quotes inside the @var{characters} parameters below should not be escaped. +The last double quote on the line will be seen as the closing quote. + +@menu +* Settings:: +* Syntax Highlighting:: +* Rebinding Keys:: +@end menu + +@node Settings +@section Settings + +The supported settings in a nanofurrc file are: + +@table @code + +@item set afterends +Make @kbd{Ctrl+Right} and @kbd{Ctrl+Delete} stop at word ends +instead of beginnings. + +@item set allow_insecure_backup +When backing up files, allow the backup to succeed even if its +permissions can't be (re)set due to special OS considerations. +You should NOT enable this option unless you are sure you need it. + +@item set atblanks +When soft line wrapping is enabled, make it wrap lines at blank characters +(tabs and spaces) instead of always at the edge of the screen. + +@item set autoindent +Automatically indent a newly created line to the same number of tabs +and/or spaces as the previous line (or as the next line if the previous +line is the beginning of a paragraph). + +@item set backup +When saving a file, back up the previous version of it, using the current +filename suffixed with a tilde (@code{~}). + +@item set backupdir "@var{directory}" +Make and keep not just one backup file, but make and keep a uniquely +numbered one every time a file is saved --- when backups are enabled +with @code{set backup} or @option{--backup} or @option{-B}. +The uniquely numbered files are stored in the specified directory. + +@item set boldtext +Use bold instead of reverse video for the title bar, status bar, +prompt bar, mini bar, key combos, line numbers, and selected text. +This can be overridden by setting the options @code{titlecolor}, +@code{statuscolor}, @code{promptcolor}, @code{minicolor}, +@code{keycolor}, @code{numbercolor}, and/or @code{selectedcolor}. + +@item set bookstyle +When justifying, treat any line that starts with whitespace as the +beginning of a paragraph (unless auto-indenting is on). + +@item set brackets "@var{characters}" +Set the characters treated as closing brackets when justifying +paragraphs. This may not include blank characters. Only closing +punctuation (see @code{set punct}), optionally followed by the specified +closing brackets, can end sentences. The default value is +"@t{"')>]@}}". + +@item set breaklonglines +Automatically hard-wrap the current line when it becomes overlong. + +@item set casesensitive +Do case-sensitive searches by default. + +@item set colonparsing +When a filename given on the command line ends in a colon plus digits +and this filename does not exist, then snip the colon plus digits and +understand the digits as a line number. If the trimmed filename does +not exist either, then repeat the process and understand the obtained +two numbers as line and column number. But if the doubly trimmed +filename does not exist either, then forget the trimming and accept +the original filename as is. To disable this colon parsing for some +file, use @code{+1} or similar before the relevant filename. + +@item set constantshow +Constantly display the cursor position on the status bar. +Note that this overrides @option{quickblank}. + +@item set cutfromcursor +Use cut-from-cursor-to-end-of-line by default, instead of cutting the whole line. + +@item set emptyline +Do not use the line below the title bar, leaving it entirely blank. + +@item set errorcolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for the status bar when an error message is displayed. +The default value is @t{bold,white,red}. +@xref{@code{set keycolor}} for valid color names. + +@item set fill @var{number} +Set the target width for justifying and automatic hard-wrapping at this +@var{number} of columns. If the value is 0 or less, wrapping occurs +at the width of the screen minus @var{number} columns, allowing the wrap +point to vary along with the width of the screen if the screen is resized. +The default value is @t{-8}. + +@item set functioncolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for the concise function descriptions +in the two help lines at the bottom of the screen. +@xref{@code{set keycolor}} for valid color names. + +@item set guidestripe @var{number} +Draw a vertical stripe at the given column, to help judge the width of the +text. (The color of the stripe can be changed with @code{set stripecolor}.) + +@item set historylog +Save the last hundred search strings and replacement strings and +executed commands, so they can be easily reused in later sessions. + +@item set indicator +Display a "scrollbar" on the righthand side of the edit window. +It shows the position of the viewport in the buffer +and how much of the buffer is covered by the viewport. + +@item set jumpyscrolling +Scroll the buffer contents per half-screen instead of per line. + +@anchor{@code{set keycolor}} +@item set keycolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for the shortcut key combos +in the two help lines at the bottom of the screen. +Valid names for the foreground and background colors are: +@code{red}, @code{green}, @code{blue}, +@code{magenta}, @code{yellow}, @code{cyan}, +@code{white}, and @code{black}. +Each of these eight names may be prefixed with the word +@code{light} to get a brighter version of that color. +The word @code{grey} or @code{gray} may be used +as a synonym for @code{lightblack}. +On a Linux console, @code{light} does not have +any effect for a background color. + +On terminal emulators that can do at least 256 colors, +other valid (but unprefixable) color names are: +@code{pink}, @code{purple}, @code{mauve}, +@code{lagoon}, @code{mint}, @code{lime}, +@code{peach}, @code{orange}, @code{latte}, +@code{rosy}, @code{beet}, @code{plum}, @code{sea}, +@code{sky}, @code{slate}, @code{teal}, @code{sage}, +@code{brown}, @code{ocher}, @code{sand}, @code{tawny}, +@code{brick}, @code{crimson}, and @code{normal} +--- where @code{normal} means the default foreground or background color. +On such emulators, the color may also be specified as a three-digit hexadecimal +number prefixed with @code{#}, with the digits representing the amounts of red, +green, and blue, respectively. This tells @command{nanofur} to select from the +available palette the color that approximates the given values. + +Either @var{fgcolor} or ,@var{bgcolor} may be left out, +and the pair may be preceded by @code{bold} and/or @code{italic} +(separated by commas) to get a bold and/or slanting typeface, +if your terminal can do those. + +@item set linenumbers +Display line numbers to the left of the text area. +(Any line with an anchor additionally gets a mark in the margin.) + +@item set locking +Enable vim-style lock-files for when editing files. + +@item set magic +When neither the file's name nor its first line give a clue, +try using libmagic to determine the applicable syntax. +(Calling libmagic can be relatively time consuming. +It is therefore not done by default.) + +@anchor{@code{set matchbrackets}} +@item set matchbrackets "@var{characters}" +Specify the opening and closing brackets that can be found by bracket +searches. This may not include blank characters. The opening set must +come before the closing set, and the two sets must be in the same order. +The default value is "@t{(<[@{)>]@}}". + +@item set minibar +Suppress the title bar and instead show information about +the current buffer at the bottom of the screen, in the space +for the status bar. In this "mini bar" the filename is shown +on the left, followed by an asterisk if the buffer has been modified. +On the right are displayed the current line and column number, the +code of the character under the cursor (in Unicode format: U+xxxx), +the same flags as are shown by @code{set stateflags}, and a percentage +that expresses how far the cursor is into the file (linewise). +When a file is loaded or saved, and also when switching between buffers, +the number of lines in the buffer is displayed after the filename. +This number is cleared upon the next keystroke, or replaced with an +[i/n] counter when multiple buffers are open. +The line plus column numbers and the character code are displayed only when +@code{set constantshow} is used, and can be toggled on and off with @kbd{M-C}. +The state flags are displayed only when @code{set stateflags} is used. + +@item set minicolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for the mini bar. +(When this option is not specified, the colors of the title bar are used.) +@xref{@code{set keycolor}} for valid color names. + +@item set mouse +Enable mouse support, so that mouse clicks can be used to place the +cursor, set the mark (with two clicks), or execute shortcuts. + +@item set multibuffer +When reading in a file with @kbd{^R}, insert it into a new buffer by default. + +@item set noconvert +Don't convert files from DOS/Mac format. + +@item set nohelp +Don't display the help lists at the bottom of the screen. + +@item set nonewlines +Don't automatically add a newline when a text does not end with one. +(This can cause you to save non-POSIX text files.) + +@item set nowrap +Deprecated option since it has become the default setting. +When needed, use @code{unset breaklonglines} instead. + +@item set numbercolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for line numbers. +@xref{@code{set keycolor}} for valid color names. + +@item set operatingdir "@var{directory}" +@command{nanofur} only reads and writes files inside "directory" and its +subdirectories. Also, the current directory is changed to here, so +files are inserted from this directory. By default, the operating +directory feature is turned off. + +@item set positionlog +Save the cursor position of files between editing sessions. +The cursor position is remembered for the 200 most-recently edited files. + +@item set preserve +Preserve the XOFF and XON sequences (@kbd{^S} and @kbd{^Q}) so that +they are caught by the terminal (stopping and resuming the output). + +@item set promptcolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for the prompt bar. +(When this option is not specified, the colors of the title bar are used.) +@xref{@code{set keycolor}} for valid color names. + +@item set punct "@var{characters}" +Set the characters treated as closing punctuation when justifying +paragraphs. This may not include blank characters. Only the +specified closing punctuation, optionally followed by closing brackets +(see @code{set brackets}), can end sentences. +The default value is "@t{!.?}". + +@item set quickblank +Make status-bar messages disappear after 1 keystroke instead of after 20. +Note that option @option{constantshow} overrides this. +When option @option{minibar} or @option{zero} is in effect, +@option{quickblank} makes a message disappear after +0.8 seconds instead of after the default 1.5 seconds. + +@item set quotestr "@var{regex}" +Set the regular expression for matching the quoting part of a line. +The default value is "@t{^([@w{ }\t]*([!#%:;>|@}]|//))+}". +(Note that @code{\t} stands for a literal Tab character.) +This makes it possible to rejustify blocks of quoted text when composing +email, and to rewrap blocks of line comments when writing source code. + +@item set rawsequences +Interpret escape sequences directly, instead of asking @code{ncurses} +to translate them. (If you need this option to get some keys to work +properly, it means that the terminfo terminal description that is used +does not fully match the actual behavior of your terminal. This can +happen when you ssh into a BSD machine, for example.) +Using this option disables @command{nanofur}'s mouse support. + +@item set rebinddelete +Interpret the @kbd{Delete} and @kbd{Backspace} keys differently so that +both work properly. You should only use this option when on your system +either @kbd{Backspace} acts like Delete or @kbd{Delete} acts like Backspace. + +@item set regexp +Do regular-expression searches by default. +Regular expressions in @command{nanofur} are of the extended type (ERE). + +@item set saveonexit +Save a changed buffer automatically on exit (@kbd{^X}); don't prompt. + +@item set scrollercolor @var{fgcolor},@var{bgcolor} +Use this color combination for the indicator alias "scrollbar". +@xref{@code{set keycolor}} for valid color names. + +@item set selectedcolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for selected text. +@xref{@code{set keycolor}} for valid color names. + +@item set showcursor +Put the cursor on the highlighted item in the file browser, and show +the cursor in the help viewer, to aid braille users and people with +poor vision. + +@item set smarthome +Make the Home key smarter. When Home is pressed anywhere but at the +very beginning of non-whitespace characters on a line, the cursor jumps +to that beginning (either forwards or backwards). If the cursor is +already at that position, it jumps to the true beginning of the line. + +@item set softwrap +Display lines that exceed the screen's width over multiple screen lines. +(You can make this soft-wrapping occur at whitespace instead of rudely at +the screen's edge, by using also @code{set atblanks}.) + +@item set speller "@var{program} [@var{argument} @dots{}]" +Use the given program to do spell checking and correcting. +@xref{@option{--speller}} for details. + +@item set spotlightcolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for highlighting a search match. +The default value is @t{black,lightyellow}. +@xref{@code{set keycolor}} for valid color names. + +@item set stateflags +Use the top-right corner of the screen for showing some state flags: +@code{I} when auto-indenting, @code{M} when the mark is on, @code{L} when +hard-wrapping (breaking long lines), @code{R} when recording a macro, +and @code{S} when soft-wrapping. +When the buffer is modified, a star (@code{*}) is shown after the +filename in the center of the title bar. + +@item set statuscolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for the status bar. +@xref{@code{set keycolor}} for valid color names. + +@item set stripecolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for the vertical guiding stripe. +@xref{@code{set keycolor}} for valid color names. + +@item set tabsize @var{number} +Use a tab size of @var{number} columns. The value of @var{number} must be +greater than 0. The default value is @t{8}. + +@item set tabstospaces +Convert each typed tab to spaces --- to the number of spaces +that a tab at that position would take up. +(Note: pasted tabs are not converted.) + +@item set titlecolor [bold,][italic,]@var{fgcolor},@var{bgcolor} +Use this color combination for the title bar. +@xref{@code{set keycolor}} for valid color names. + +@item set trimblanks +Remove trailing whitespace from wrapped lines when automatic +hard-wrapping occurs or when text is justified. + +@item set unix +Save a file by default in Unix format. This overrides nanofur's +default behavior of saving a file in the format that it had. +(This option has no effect when you also use @code{set noconvert}.) + +@anchor{Whitespace} +@item set whitespace "@var{characters}" +Set the two characters used to indicate the presence of tabs and +spaces. They must be single-column characters. The default pair +for a UTF-8 locale is @t{"»·"}, and for other locales @t{">."}. + +@item set wordbounds +Detect word boundaries differently by treating punctuation +characters as part of a word. + +@item set wordchars "@var{characters}" +Specify which other characters (besides the normal alphanumeric ones) +should be considered as parts of words. When using this option, you +probably want to unset @code{wordbounds}. + +@item set zap +Let an unmodified @kbd{Backspace} or @kbd{Delete} erase the marked region +(instead of a single character, and without affecting the cutbuffer). + +@item set zero +Hide all elements of the interface (title bar, status bar, and help lines) +and use all rows of the terminal for showing the contents of the buffer. +The status bar appears only when there is a significant message, +and disappears after 1.5 seconds or upon the next keystroke. +With @kbd{M-Z} the title bar plus status bar can be toggled. +With @kbd{M-X} the help lines. + +@end table + +@node Syntax Highlighting +@section Syntax Highlighting + +Coloring the different syntactic elements of a file +is done via regular expressions (see the @code{color} command below). +This is inherently imperfect, because regular expressions are not +powerful enough to fully parse a file. Nevertheless, regular +expressions can do a lot and are easy to make, so they are a +good fit for a small editor like @command{nanofur}. + +See @file{/usr/share/nanofur/} and @file{/usr/share/nanofur/extra/} +for the syntax-coloring definitions that are available out of the box. + +All regular expressions in @command{nanofur} are POSIX extended regular expressions +(ERE). This means that @code{.}, @code{?}, @code{*}, @code{+}, @code{^}, +@code{$}, and several other characters are special. +The period @code{.} matches any single character, +@code{?} means the preceding item is optional, +@code{*} means the preceding item may be matched zero or more times, +@code{+} means the preceding item must be matched one or more times, +@code{^} matches the beginning of a line, and @code{$} the end, +@code{\<} matches the start of a word, and @code{\>} the end, +and @code{\s} matches a blank. +It also means that lookahead and lookbehind are not possible. +A complete explanation can be found in the manual of GNU grep: +@code{info grep regular}. + +Each regular expression in a @file{nanofurrc} file should be wrapped in +double quotes (@code{""}). Multiple regular expressions can follow +each other on a line by separating them with blanks. This means that +a regular expression cannot contain a double quote followed by a blank. +When you need this combination inside a regular expression, +then either the double quote or the blank should be put +between square brackets (@code{[]}). + +A separate syntax can be defined for each kind of file +via the following commands in a nanofurrc file: + +@table @code + +@item syntax @var{name} ["@var{fileregex}" @dots{}] +Start the definition of a syntax with this @var{name}. +All subsequent @code{color} and other such commands +are added to this syntax, until a new @code{syntax} +command is encountered. + +When @command{nanofur} is run, this syntax is automatically +activated (for the relevant buffer) if the absolute filename +matches the extended regular expression @var{fileregex}. +Or the syntax can be explicitly activated (for all buffers) +by using the @option{-Y} or @option{--syntax} +command-line option followed by the @var{name}. + +The @code{default} syntax is special: it takes no @var{fileregex}, +and applies to files that don't match any syntax's regexes. +The @code{none} syntax is reserved; specifying it on the +command line is the same as not having a syntax at all. + +@item header "@var{regex}" @dots{} +If from all defined syntaxes no @var{fileregex} matched, then compare +this @var{regex} (or regexes) against the first line of the current file, +to determine whether this syntax should be used for it. + +@item magic "@var{regex}" @dots{} +If no @var{fileregex} matched and no @code{header} regex matched +either, then compare this @var{regex} (or regexes) against the +result of querying the @code{magic} database about the current +file, to determine whether this syntax should be used for it. +(This querying is done only when @code{libmagic} is actually installed +on the system and @option{--magic} or @code{set magic} was given.) + +@item formatter @var{program} [@var{argument} @dots{}] +Run the given @var{program} on the full contents of the current buffer. + +@item linter @var{program} [@var{argument} @dots{}] +Use the given @var{program} to do a syntax check on the current buffer. + +@item comment "@var{string}" +Use the given string for commenting and uncommenting lines. +If the string contains a vertical bar or pipe character (@t{|}), +this designates bracket-style comments; for example, @t{"/*|*/"} for +CSS files. The characters before the pipe are prepended to the line and the +characters after the pipe are appended at the end of the line. If no pipe +character is present, the full string is prepended; for example, @t{"#"} for +Python files. If empty double quotes are specified, the comment/uncomment +functions are disabled; for example, @t{""} for JSON. +The default value is "@t{#}". + +@item tabgives "@var{string}" +Make the key produce the given @var{string}. Useful for languages like +Python that want to see only spaces for indentation. +This overrides the setting of the @code{tabstospaces} option. + +@item color [bold,][italic,]@var{fgcolor},@var{bgcolor} "@var{regex}" @dots{} +Paint all pieces of text that match the extended regular expression "regex" +with the given foreground and background colors, at least one of which must +be specified. Valid color names are: +@code{red}, @code{green}, @code{blue}, +@code{magenta}, @code{yellow}, @code{cyan}, +@code{white}, and @code{black}. +Each of these eight names may be prefixed with the word +@code{light} to get a brighter version of that color. +The word @code{grey} or @code{gray} may be used +as a synonym for @code{lightblack}. +On a Linux console, @code{light} does not have +any effect for a background color. + +On terminal emulators that can do at least 256 colors, +other valid (but unprefixable) color names are: +@code{pink}, @code{purple}, @code{mauve}, +@code{lagoon}, @code{mint}, @code{lime}, +@code{peach}, @code{orange}, @code{latte}, +@code{rosy}, @code{beet}, @code{plum}, @code{sea}, +@code{sky}, @code{slate}, @code{teal}, @code{sage}, +@code{brown}, @code{ocher}, @code{sand}, @code{tawny}, +@code{brick}, @code{crimson}, and @code{normal} +--- where @code{normal} means the default foreground or background color. +On such emulators, the color may also be specified as a three-digit hexadecimal +number prefixed with @code{#}, with the digits representing the amounts of red, +green, and blue, respectively. This tells @command{nanofur} to select from the +available palette the color that approximates the given values. + +The color pair may be preceded by @code{bold} and/or @code{italic} +(separated by commas) to get a bold and/or slanting typeface, +if your terminal can do those. + +All coloring commands are applied in the order in which they are specified, +which means that later commands can recolor stuff that was colored earlier. + +@item icolor [bold,][italic,]@var{fgcolor},@var{bgcolor} "@var{regex}" @dots{} +Same as above, except that the matching is case insensitive. + +@item color [bold,][italic,]@var{fgcolor},@var{bgcolor} start="@var{fromrx}" end="@var{torx}" +Paint all pieces of text whose start matches extended regular expression +"fromrx" and whose end matches extended regular expression "torx" with +the given foreground and background colors, at least one of +which must be specified. This means that, after an initial instance of +"fromrx", all text until the first instance of "torx" is colored. +This allows syntax highlighting to span multiple lines. + +@item icolor [bold,][italic,]@var{fgcolor},@var{bgcolor} start="@var{fromrx}" end="@var{torx}" +Same as above, except that the matching is case insensitive. + +@item include "@var{syntaxfile}" +Read in self-contained color syntaxes from "syntaxfile". Note that +"syntaxfile" may contain only the above commands, from @code{syntax} +to @code{icolor}. + +@item extendsyntax @var{name} @var{command} @var{argument} @dots{} +Extend the syntax previously defined as "@var{name}" with another @var{command}. +This allows you to add a new @code{color}, @code{icolor}, @code{header}, +@code{magic}, @code{formatter}, @code{linter}, @code{comment}, +or @code{tabgives} command to an already +defined syntax --- useful when you want to slightly improve a syntax defined +in one of the system-installed files (which normally are not writable). + +@end table + +@node Rebinding Keys +@section Rebinding Keys + +Key bindings can be changed via the following three commands in a +nanofurrc file: + +@table @code + +@item bind key function menu +Rebinds @code{key} to @code{function} in the context of @code{menu} +(or in all menus where the function exists when @code{all} is used). + +@item bind key "string" menu +Makes @code{key} produce @code{string} in the context of @code{menu} +(or in all menus where the key exists when @code{all} is used). +Besides literal text and/or control codes, the @code{string} may contain +function names between braces. These functions are invoked when the +key is typed. To include a literal opening brace, use @code{@{@{@}}. + +@item unbind key menu +Unbinds @code{key} from @code{menu} +(or from all menus where the key exists when @code{all} is used). + +@end table + +Note that @code{bind key "@{function@}" menu} is equivalent to +@code{bind key function menu}, except that for the latter form +@command{nanofur} checks the availability of the @code{function} +in the given @code{menu} at startup time (and reports an error if +it does not exist there), whereas for the first form @command{nanofur} +checks at execution time that the @code{function} exists but not +whether it makes any sense in the current menu. The user has to take +care that a function name between braces (or any sequence of them) +is appropriate. Strange behavior or even a crash can result when +the braced name is unfitting. + +@sp 1 +The format of @code{key} should be one of: + +@indentedblock +@table @asis + +@item @code{^@var{X}} +where @var{X} is a Latin letter, or one of several +ASCII characters (@@, ], \, ^, _), or the word "Space". +Example: @code{^C}. + +@item @code{M-@var{X}} +where @var{X} is any ASCII character except [, or the word "Space". +Example: @code{M-8}. + +@item @code{Sh-M-@var{X}} +where @var{X} is a Latin letter. +Example: @code{Sh-M-U}. +By default, each Meta+letter keystroke does the same as the corresponding +Shift+Meta+letter. But when any Shift+Meta bind is made, that will +no longer be the case, for all letters. + +@item @code{F@var{n}} +where @var{n} is a numeric value from 1 to 24. +Example: @code{F10}. +(Often, @code{F13} to @code{F24} can be typed as @code{F1} to @code{F12} +with Shift.) + +@item @code{Ins} or @code{Del} + +@end table +@end indentedblock + +@sp 1 +Rebinding @code{^M} (Enter) or @code{^I} (Tab) is probably not a good idea. +Rebinding @code{^[} (Esc) is not possible, because its keycode +is the starter byte of Meta keystrokes and escape sequences. +Rebinding any of the dedicated cursor-moving keys (the arrows, Home, End, +PageUp and PageDown) is not possible. +On some terminals it's not possible to rebind @code{^H} (unless @code{--raw} +is used) because its keycode is identical to that of the Backspace key. + +@sp 1 +Valid names for the @code{function} to be bound are: + +@table @code + +@item help +Invokes the help viewer. + +@item cancel +Cancels the current command. + +@item exit +Exits from the program (or from the help viewer or file browser). + +@item writeout +Writes the current buffer to disk, asking for a name. + +@item savefile +Writes the current file to disk without prompting. + +@item insert +Inserts a file into the current buffer (at the current cursor position), +or into a new buffer when option @code{multibuffer} is set. + +@item whereis +Starts a forward search for text in the current buffer --- or for filenames +matching a string in the current list in the file browser. + +@item wherewas +Starts a backward search for text in the current buffer --- or for filenames +matching a string in the current list in the file browser. + +@item findprevious +Searches the next occurrence in the backward direction. + +@item findnext +Searches the next occurrence in the forward direction. + +@item replace +Interactively replaces text within the current buffer. + +@item cut +Cuts and stores the current line (or the marked region). + +@item copy +Copies the current line (or the marked region) without deleting it. + +@item paste +Pastes the currently stored text into the current buffer at the +current cursor position. + +@item zap +Throws away the current line (or the marked region). +(This function is bound by default to @kbd{Alt+Delete}.) + +@item chopwordleft +Deletes from the cursor position to the beginning of the preceding word. +(This function is bound by default to @kbd{Shift+Ctrl+Delete}. If your terminal +produces @code{^H} for @kbd{Ctrl+Backspace}, you can make @kbd{Ctrl+Backspace} delete +the word to the left of the cursor by rebinding @kbd{^H} to this function.) + +@item chopwordright +Deletes from the cursor position to the beginning of the next word. +(This function is bound by default to @kbd{Ctrl+Delete}.) + +@item cutrestoffile +Cuts all text from the cursor position till the end of the buffer. + +@item mark +Sets the mark at the current position, to start selecting text. +Or, when it is set, unsets the mark. + +@item location +Reports the current position of the cursor in the buffer: +the line, column, and character positions. + +@item wordcount +Counts and reports on the status bar the number of lines, words, +and characters in the current buffer (or in the marked region). + +@item execute +Prompts for a program to execute. The program's output will be inserted +into the current buffer (or into a new buffer when @kbd{M-F} is toggled). + +@item speller +Invokes a spell-checking program, either the default @command{hunspell} +or GNU @command{spell}, or the one defined by @option{--speller} or +@code{set speller}. + +@item formatter +Invokes a full-buffer-processing program (if the active syntax defines one). +(The current buffer is written out to a temporary file, the program +is run on it, and then the temporary file is read back in, replacing +the contents of the buffer.) + +@item linter +Invokes a syntax-checking program (if the active syntax defines one). +If this program produces lines of the form "filename:linenum:charnum: +some message", then the cursor is put at the indicated position +in the mentioned file while showing "some message" on the status bar. +You can move from message to message with @kbd{PgUp} and @kbd{PgDn}, +and leave linting mode with @kbd{^C} or @kbd{Enter}. + +@item justify +Justifies the current paragraph (or the marked region). +A paragraph is a group of contiguous lines that, apart from possibly +the first line, all have the same indentation. The beginning of a +paragraph is detected by either this lone line with a differing +indentation or by a preceding blank line. + +@item fulljustify +Justifies the entire current buffer (or the marked region). + +@item indent +Indents (shifts to the right) the current line or the marked lines. + +@item unindent +Unindents (shifts to the left) the current line or the marked lines. + +@item comment +Comments or uncomments the current line or the marked lines, +using the comment style specified in the active syntax. + +@item complete +Completes (when possible) the fragment before the cursor +to a full word found elsewhere in the current buffer. + +@item left +Goes left one position (in the editor or browser). + +@item right +Goes right one position (in the editor or browser). + +@item up +Goes one line up (in the editor or browser). + +@item down +Goes one line down (in the editor or browser). + +@item scrollup +Scrolls the viewport up one row (meaning that the text slides down) +while keeping the cursor in the same text position, if possible. +(This function is bound by default to @kbd{Alt+Up}. +If @kbd{Alt+Up} does nothing on your Linux console, see the FAQ: +@url{https://nanofur-editor.org/dist/latest/faq.html#4.1}.) + +@item scrolldown +Scrolls the viewport down one row (meaning that the text slides up) +while keeping the cursor in the same text position, if possible. +(This function is bound by default to @kbd{Alt+Down}.) + +@item center +Scrolls the line with the cursor to the middle of the viewport. + +@item cycle +Scrolls the line with the cursor first to the middle of the viewport, +then to the top, then to the bottom. + +@item prevword +Moves the cursor to the beginning of the previous word. + +@item nextword +Moves the cursor to the beginning of the next word. + +@item home +Moves the cursor to the beginning of the current line. + +@item end +Moves the cursor to the end of the current line. + +@item beginpara +Moves the cursor to the beginning of the current paragraph. + +@item endpara +Moves the cursor to the end of the current paragraph. + +@item prevblock +Moves the cursor to the beginning of the current or preceding block of text. +(Blocks are separated by one or more blank lines.) + +@item nextblock +Moves the cursor to the beginning of the next block of text. + +@item toprow +Moves the cursor to the first row in the viewport. + +@item bottomrow +Moves the cursor to the last row in the viewport. + +@item pageup +Goes up one screenful. + +@item pagedown +Goes down one screenful. + +@item firstline +Goes to the first line of the file. + +@item lastline +Goes to the last line of the file. + +@item gotoline +Goes to a specific line (and column if specified). Negative numbers count +from the end of the file (and end of the line). + +@item findbracket +Moves the cursor to the bracket (or brace or parenthesis, etc.) that matches +(pairs) with the one under the cursor. @xref{@code{set matchbrackets}}. + +@item anchor +Places an anchor at the current line, or removes it when already present. +(An anchor is visible when line numbers are activated.) + +@item prevanchor +Goes to the first anchor before the current line. + +@item nextanchor +Goes to the first anchor after the current line. + +@item prevbuf +Switches to editing/viewing the previous buffer when multiple buffers are open. + +@item nextbuf +Switches to editing/viewing the next buffer when multiple buffers are open. + +@item verbatim +Inserts the next keystroke verbatim into the file, or begins Unicode input +when a hexadecimal digit is typed (@pxref{Entering Text} for details). + +@item tab +Inserts a tab at the current cursor location. + +@item enter +Inserts a new line below the current one. + +@item delete +Deletes the character under the cursor. + +@item backspace +Deletes the character before the cursor. + +@item recordmacro +Starts the recording of keystrokes --- the keystrokes are stored +as a macro. When already recording, the recording is stopped. + +@item runmacro +Replays the keystrokes of the last recorded macro. + +@item undo +Undoes the last performed text action (add text, delete text, etc). + +@item redo +Redoes the last undone action (i.e., it undoes an undo). + +@item refresh +Refreshes the screen. + +@item suspend +Suspends the editor and returns control to the shell +(until you tell the process to resume execution with @kbd{fg}). + +@item casesens +Toggles whether searching/replacing ignores or respects the case of +the given characters. + +@item regexp +Toggles whether searching/replacing uses literal strings or regular expressions. + +@item backwards +Toggles whether searching/replacing goes forward or backward. + +@item older +Retrieves the previous (earlier) entry at a prompt. + +@item newer +Retrieves the next (later) entry at a prompt. + +@item flipreplace +Toggles between searching for something and replacing something. + +@item flipgoto +Toggles between searching for text and targeting a line number. + +@item flipexecute +Switches from inserting a file to executing a command. + +@item flippipe +When executing a command, toggles whether the current buffer (or marked +region) is piped to the command. + +@item flipnewbuffer +Toggles between inserting into the current buffer and into a new +empty buffer. + +@item flipconvert +When reading in a file, toggles between converting and not converting +it from DOS/Mac format. Converting is the default. + +@item dosformat +When writing a file, switches to writing a DOS format (CR/LF). + +@item macformat +When writing a file, switches to writing a Mac format. + +@item append +When writing a file, appends to the end instead of overwriting. + +@item prepend +When writing a file, 'prepends' (writes at the beginning) instead of overwriting. + +@item backup +When writing a file, creates a backup of the current file. + +@item discardbuffer +When about to write a file, discard the current buffer without saving. +(This function is bound by default only when option @option{--saveonexit} +is in effect.) + +@item browser +Starts the file browser (in the Read File and Write Out menus), +allowing to select a file from a list. + +@item gotodir +Goes to a directory to be specified, allowing to browse anywhere +in the filesystem. + +@item firstfile +Goes to the first file in the list when using the file browser. + +@item lastfile +Goes to the last file in the list when using the file browser. + +@item nohelp +Toggles the presence of the two-line list of key bindings at the bottom of the screen. +(This toggle is special: it is available in all menus except the help viewer +and the linter. All further toggles are available in the main menu only.) + +@item zero +Toggles the presence of title bar and status bar. + +@item constantshow +Toggles the constant display of the current line, column, and character positions. + +@item softwrap +Toggles the displaying of overlong lines on multiple screen lines. + +@item linenumbers +Toggles the display of line numbers in front of the text. + +@item whitespacedisplay +Toggles the showing of whitespace. + +@item nosyntax +Toggles syntax highlighting. + +@item smarthome +Toggles the smartness of the Home key. + +@item autoindent +Toggles whether a newly created line will contain the same amount of leading +whitespace as the preceding line --- or as the next line if the preceding line +is the beginning of a paragraph. + +@item cutfromcursor +Toggles whether cutting text cuts the whole line or just from the current cursor +position to the end of the line. + +@item breaklonglines +Toggles whether the overlong part of a line is hard-wrapped to the next line. + +@item tabstospaces +Toggles whether typed tabs are converted to spaces. + +@item mouse +Toggles mouse support. + +@end table + +@sp 1 +Valid names for @code{menu} are: + +@table @code + +@item main +The main editor window where text is entered and edited. + +@item help +The help-viewer menu. + +@item search +The search menu (AKA whereis). + +@item replace +The 'search to replace' menu. + +@item replacewith +The 'replace with' menu, which comes up after 'search to replace'. + +@item yesno +The 'yesno' menu, where the Yes/No/All/Cancel question is asked. + +@item gotoline +The 'goto line (and column)' menu. + +@item writeout +The 'write file' menu. + +@item insert +The 'insert file' menu. + +@item browser +The 'file browser' menu, for selecting a file to be opened or +inserted or written to. + +@item whereisfile +The 'search for a file' menu in the file browser. + +@item gotodir +The 'go to directory' menu in the file browser. + +@item execute +The menu for inserting the output from an external command, +or for filtering the buffer (or the marked region) through +an external command, or for executing one of several tools. + +@item spell +The menu of the integrated spell checker where the user can edit a misspelled word. + +@item linter +The linter menu, which allows jumping through the linting messages. + +@item all +A special name that encompasses all menus. For @code{bind} it means +all menus where the specified @code{function} exists; for @code{unbind} +it means all menus where the specified @code{key} exists. + +@end table + + +@node Pico Compatibility +@chapter Pico Compatibility + +@command{nanofur} emulates Pico quite closely, but there +are some differences between the two editors: + +@table @code + +@item Hard-Wrapping +Unlike Pico, @command{nanofur} does not automatically hard-wrap the current +line when it becomes overlong during typing. This hard-wrapping can be +switched on with the @option{--breaklonglines} option. With that option, +@command{nanofur} by default breaks lines at screen width minus eight columns, +whereas Pico does it at screen width minus six columns. You can make +@command{nanofur} do as Pico by using @option{--fill=-6}. + +@item Scrolling +By default, @command{nanofur} scrolls just one line (instead of half +a screen) when the cursor is moved to a line that is just out of view. +And when paging up or down, @command{nanofur} keeps the cursor in the same +screen position as much as possible, instead of always placing it on the +first line of the viewport. The Pico-like behavior can be obtained +with the @option{--jumpyscrolling} option. + +@item Edit Area +Pico never uses the line directly below the title bar, leaving it always +blank. @command{nanofur} includes this line in the editing area, in order +to not waste space, and because in this way it is slightly clearer where +the text starts. If you are accustomed to this line being empty, you can +get it back with the @option{--emptyline} option. + +@item Interactive Replace +Instead of allowing you to replace either just one occurrence of a search +string or all of them, @command{nanofur}'s replace function is interactive: +it pauses at each found search string and asks whether to replace this +instance. You can then choose Yes, or No (skip this one), or All (don't +ask any more), or Cancel (stop with replacing). + +@item Search and Replace History +When the option @option{-H} or @option{--historylog} is given (or set in +a nanofurrc file), text entered as search or replace strings is stored. +These strings can be accessed with the up/down arrow keys at their +respective prompts, or you can +type the first few characters and then use @kbd{Tab} to cycle through the +matching strings. A retrieved string can subsequently be edited. + +@item Position History +When the option @option{-P} or @option{--positionlog} is given (or set in +a nanofurrc file), @command{nanofur} will store the position of the cursor +when you close a file, and will place the cursor in that position +again when you later reopen the file. + +@item Current Cursor Position +The output of the "Display Cursor Position" command (@kbd{^C}) displays +not only the current line and character position of the cursor, +but also (between the two) the current column position. + +@item Spell Checking +In the internal spell checker misspelled words are sorted alphabetically +and trimmed for uniqueness, such that the strings 'Aplpe' and 'aplpe' +will be offered for correction separately. + +@item Writing Selected Text to Files +When using the Write-Out key (@kbd{^O}), text that has been selected using the +marking key (@kbd{^^}) can not just be written out to a new (or existing) file, +it can also be appended or prepended to an existing file. + +@item Reading Text from a Command +When using the Read-File key (@kbd{^R}), @command{nanofur} can not just read a file, +it can also read the output of a command to be run (@kbd{^X}). + +@item Reading from Working Directory +By default, Pico reads files from the user's home directory (when +using @kbd{^R}), but it writes files to the current working directory +(when using @kbd{^O}). @command{nanofur} makes this symmetrical: always reading +from and writing to the current working directory --- the directory +that @command{nanofur} was started in. + +@item File Browser +In the file browser, @command{nanofur} does not implement the Add, Copy, +Rename, and Delete commands that Pico provides. In @command{nanofur} the +browser is just a file browser, not a file manager. + +@item Toggles +Many options which alter the functionality of the program can be +"toggled" on or off using Meta key sequences, meaning the program does +not have to be restarted to turn a particular feature on or off. +@xref{Feature Toggles} for a list of options that can be toggled. +Or see the list at the end of the main internal help text (@kbd{^G}) instead. + +@end table + + +@node Building and its Options +@chapter Building and its Options + +Building @command{nanofur} from source is straightforward if you are +familiar with compiling programs with autoconf support: + +@blankline +@example + tar -xf nanofur-x.y.tar.gz + cd nanofur-x.y + ./configure + make + make install +@end example +@blankline + +The possible options to @code{./configure} are: + +@table @code + +@item --disable-browser +Exclude the file browser that can be called with @kbd{^T} when +wanting to read or write a file. + +@item --disable-color +Exclude support for syntax coloring. This also eliminates the @option{-Y} +command-line option, which allows choosing a specific syntax. + +@item --disable-comment +Exclude the single-keystroke comment/uncomment function (@w{@kbd{M-3}}). + +@item --disable-extra +Exclude the Easter egg: a crawl of major contributors. + +@item --disable-formatter +Exclude the code for calling a formatting tool. + +@item --disable-help +Exclude the help texts (@kbd{^G}). This makes the binary much smaller, +but also makes it difficult for new users to learn more than very basic +things about using the editor. + +@item --disable-histories +Exclude the code for handling the history files: the search and +replace strings that were used, the commands that were executed, +and the cursor position at which each file was closed. +This also eliminates the @option{-H} and @option{-P} command-line +options, which switch on the storing of search/replace strings, +executed commands, and cursor positions. + +@item --disable-justify +Exclude the text-justification functions (@kbd{^J} and @kbd{M-J}). + +@item --disable-libmagic +Exclude the code for using the library of magic-number tests (for +determining the file type and thus which syntax to use for coloring --- +in most cases the regexes for filename and header line will be enough). + +@item --disable-linenumbers +Exclude the ability to show line numbers. This also eliminates +the @option{-l} command-line option, which turns line numbering on. + +@item --disable-linter +Exclude the code for calling a linting tool. + +@item --disable-mouse +Exclude all mouse functionality. This also eliminates the @option{-m} +command-line option, which enables the mouse functionality. + +@item --disable-multibuffer +Exclude support for opening multiple files at a time and switching +between them. This also eliminates the @option{-F} command-line option, +which causes a file to be read into a separate buffer by default. + +@item --disable-nanofurrc +Exclude support for reading the nanofurrc files at startup. With such +support, you can store custom settings in a system-wide and a per-user +nanofurrc file rather than having to pass command-line options to get +the desired behavior. @xref{Nanofurrc Files} for more info. +Disabling this also eliminates the @option{-I} command-line option, +which inhibits the reading of nanofurrc files. + +@item --disable-operatingdir +Exclude the code for setting an operating directory. This also eliminates +the @option{-o} command-line option, which sets the operating directory. + +@item --disable-speller +Exclude the code for spell checking. This also eliminates the @option{-s} +command-line option, which allows specifying an alternate spell checker. + +@item --disable-tabcomp +Exclude tab completion (when nanofur asks for a filename or search string +or replace string or command to execute). + +@item --disable-wordcomp +Exclude word completion (@kbd{^]}). + +@item --disable-wrapping +Exclude all hard-wrapping of overlong lines. This also eliminates the +@option{-b} and @option{-w} command-line options, which switch automatic +long-line wrapping on and off, respectively. + +@item --enable-tiny +This option implies all of the above. It also disables some other +internals of the editor, like the function toggles, the marking of text, +the undo/redo code, line anchors, the recording and playback of a macro, +softwrapping, and the cut-to-end-of-line code. These things stay disabled +also when using the enabling counterpart of the above options together with +@option{--enable-tiny} to switch specific features back on. + +@item --enable-debug +Include some code for runtime debugging output. This can get messy, so +chances are you only want this feature when you're working on the nanofur source. + +@item --disable-nls +Exclude Native Language support. This disables the use of any +available GNU @command{nanofur} translations. + +@item --enable-utf8 +Include support for handling and displaying Unicode files. +This requires a "wide" version of the curses library. + +@item --disable-utf8 +Exclude support for handling and displaying Unicode files. Normally the +configure script auto-detects whether to enable UTF-8 support or not. +You can use this or the previous option to override that detection. + +@item --enable-altrcname=@var{name} +Use the file with the given @var{name} (in the user's home directory) +as nanofur's settings file, instead of the default @code{.nanofurrc}. + +@end table + +@html +
+@end html + +@iftex +@contents +@end iftex + +@bye diff --git a/doc/nanofurrc.5 b/doc/nanofurrc.5 new file mode 100644 index 0000000..cdfbe91 --- /dev/null +++ b/doc/nanofurrc.5 @@ -0,0 +1,1109 @@ +.\" Copyright (C) 2003-2011, 2013-2024 Free Software Foundation, Inc. +.\" +.\" This document is dual-licensed. You may distribute and/or modify it +.\" under the terms of either of the following licenses: +.\" +.\" * The GNU General Public License, as published by the Free Software +.\" Foundation, version 3 or (at your option) any later version. You +.\" should have received a copy of the GNU General Public License +.\" along with this program. If not, see +.\" . +.\" +.\" * The GNU Free Documentation License, as published by the Free +.\" Software Foundation, version 1.2 or (at your option) any later +.\" version, with no Invariant Sections, no Front-Cover Texts, and no +.\" Back-Cover Texts. You should have received a copy of the GNU Free +.\" Documentation License along with this program. If not, see +.\" . +.\" +.TH NANOFURRC 5 "version 8.2" "September 2024" + +.SH NAME +nanofurrc \- GNU nanofur's configuration file + +.SH DESCRIPTION +The \fInanofurrc\fP files contain the default settings for \fBnanofur\fP, +a small and friendly text editor. During startup, if \fB\-\-rcfile\fR +is not given, \fBnanofur\fR reads two files: first the system-wide settings, +from \fI/etc/nanofurrc\fP (the exact path might be different on your system), +and then the user-specific settings, either from \fI~/.nanofurrc\fR or from +\fI$XDG_CONFIG_HOME/nanofur/nanofurrc\fR or from \fI~/.config/nanofur/nanofurrc\fR, +whichever is encountered first. If \fB\-\-rcfile\fR is given, +\fBnanofur\fR reads just the specified settings file. + +.SH NOTICE +Since version 8.0, to be newcomer friendly, \fB^F\fR starts a forward search, +\fB^B\fR starts a backward search, \fBM\-F\fR searches the next occurrence +forward, and \fBM\-B\fR searches the next occurrence backward. If you want +those keystrokes to do what they did before version 8.0, add the following +lines at the end of your \fInanofurrc\fR file: +.sp +.RS 4 +.B bind ^F forward main +.br +.B bind ^B back main +.br +.B bind M\-F formatter main +.br +.B bind M\-B linter main +.RE +.sp + +.\" Never hyphenate these: +.hw ncurses terminfo + +.SH OPTIONS +The configuration file accepts a series of \fBset\fP and \fBunset\fP +commands, which can be used to configure nanofur on startup without using +command-line options. Additionally, there are some commands to define +syntax highlighting and to rebind keys -- see the two separate sections +on those. \fBnanofur\fP reads one command per line. +All commands and keywords should be written in lowercase. +.sp +Options in \fInanofurrc\fP files take precedence over nanofur's defaults, and +command-line options override \fInanofurrc\fP settings. Also, options that +do not take an argument are unset by default. So using the \fBunset\fR +command is only needed when wanting to override a setting of the system's +\fInanofurrc\fR file in your own \fInanofurrc\fR. Options that take an +argument cannot be unset. +.sp +Quotes inside the \fIcharacters\fR parameters below should not be escaped. +The last double quote on the line will be seen as the closing quote. +.sp +The supported commands and arguments are: +.TP 3 +.B set afterends +Make Ctrl+Right and Ctrl+Delete stop at word ends instead of beginnings. +.TP +.B set allow_insecure_backup +When backing up files, allow the backup to succeed even if its permissions +can't be (re)set due to special OS considerations. You should +NOT enable this option unless you are sure you need it. +.TP +.B set atblanks +When soft line wrapping is enabled, make it wrap lines at blank characters +(tabs and spaces) instead of always at the edge of the screen. +.TP +.B set autoindent +Automatically indent a newly created line to the same number of tabs +and/or spaces as the previous line (or as the next line if the previous +line is the beginning of a paragraph). +.TP +.B set backup +When saving a file, create a backup file by adding a tilde (\fB~\fP) to +the file's name. +.TP +.B set backupdir "\fIdirectory\fP" +Make and keep not just one backup file, but make and keep a uniquely +numbered one every time a file is saved -- when backups are enabled +with \fBset backup\fR or \fB\-\-backup\fR or \fB\-B\fR. +The uniquely numbered files are stored in the specified \fIdirectory\fR. +.TP +.B set boldtext +Use bold instead of reverse video for the title bar, status bar, +prompt bar, mini bar, key combos, line numbers, and selected text. +This can be overridden by setting the options +\fBtitlecolor\fP, \fBstatuscolor\fP, \fBpromptcolor\fP, \fBminicolor\fP, +\fBkeycolor\fP, \fBnumbercolor\fP, and/or \fBselectedcolor\fP. +.TP +.B set bookstyle +When justifying, treat any line that starts with whitespace as the +beginning of a paragraph (unless auto-indenting is on). +.TP +.BI "set brackets """ characters """ +Set the characters treated as closing brackets when justifying +paragraphs. This may not include blank characters. Only closing +punctuation (see \fBset punct\fP), optionally followed by the specified +closing brackets, can end sentences. The default value is "\fB\(dq')>]}\fR". +.TP +.B set breaklonglines +Automatically hard-wrap the current line when it becomes overlong. +.TP +.B set casesensitive +Do case-sensitive searches by default. +.TP +.B set colonparsing +When a filename given on the command line ends in a colon plus digits +and this filename does not exist, then snip the colon plus digits and +understand the digits as a line number. If the trimmed filename does +not exist either, then repeat the process and understand the obtained +two numbers as line and column number. But if the doubly trimmed +filename does not exist either, then forget the trimming and accept +the original filename as is. To disable this colon parsing for some +file, use \fB+1\fR or similar before the relevant filename. +.TP +.B set constantshow +Constantly display the cursor position in the status bar. +This overrides the option \fBquickblank\fR. +.TP +.B set cutfromcursor +Use cut-from-cursor-to-end-of-line by default, instead of cutting the whole line. +.TP +.B set emptyline +Do not use the line below the title bar, leaving it entirely blank. +.TP +.B set errorcolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the status bar when an error message is displayed. +The default value is \fBbold,white,red\fR. +See \fBset titlecolor\fR for valid color names. +.TP +.B set fill \fInumber\fR +Set the target width for justifying and automatic hard-wrapping at this +\fInumber\fR of columns. If the value is 0 or less, wrapping occurs +at the width of the screen minus \fInumber\fR columns, allowing the wrap +point to vary along with the width of the screen if the screen is resized. +The default value is \fB\-8\fR. +.TP +.B set functioncolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the concise function descriptions +in the two help lines at the bottom of the screen. +See \fBset titlecolor\fR for more details. +.TP +.B set guidestripe \fInumber +Draw a vertical stripe at the given column, to help judge the width of the +text. (The color of the stripe can be changed with \fBset stripecolor\fR.) +.TP +.B set historylog +Save the last hundred search strings and replacement strings and +executed commands, so they can be easily reused in later sessions. +.TP +.B set indicator +Display a "scrollbar" on the righthand side of the edit window. +It shows the position of the viewport in the buffer +and how much of the buffer is covered by the viewport. +.TP +.B set jumpyscrolling +Scroll the buffer contents per half-screen instead of per line. +.TP +.B set keycolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the shortcut key combos +in the two help lines at the bottom of the screen. +See \fBset titlecolor\fR for more details. +.TP +.B set linenumbers +Display line numbers to the left of the text area. +(Any line with an anchor additionally gets a mark in the margin.) +.TP +.B set locking +Enable vim-style lock-files for when editing files. +.TP +.B set magic +When neither the file's name nor its first line give a clue, +try using libmagic to determine the applicable syntax. +(Calling libmagic can be relatively time consuming. +It is therefore not done by default.) +.TP +.BI "set matchbrackets """ characters """ +Specify the opening and closing brackets that can be found by bracket +searches. This may not include blank characters. The opening set must +come before the closing set, and the two sets must be in the same order. +The default value is "\fB(<[{)>]}\fP". +.TP +.B set minibar +Suppress the title bar and instead show information about +the current buffer at the bottom of the screen, in the space +for the status bar. In this "mini bar" the filename is shown +on the left, followed by an asterisk if the buffer has been modified. +On the right are displayed the current line and column number, the +code of the character under the cursor (in Unicode format: U+xxxx), +the same flags as are shown by \fBset stateflags\fR, and a percentage +that expresses how far the cursor is into the file (linewise). +When a file is loaded or saved, and also when switching between buffers, +the number of lines in the buffer is displayed after the filename. +This number is cleared upon the next keystroke, or replaced with an +[i/n] counter when multiple buffers are open. +The line plus column numbers and the character code are displayed only when +\fBset constantshow\fR is used, and can be toggled on and off with \fBM\-C\fR. +The state flags are displayed only when \fBset stateflags\fR is used. +.TP +.B set minicolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the mini bar. +(When this option is not specified, the colors of the title bar are used.) +See \fBset titlecolor\fR for more details. +.TP +.B set mouse +Enable mouse support, if available for your system. When enabled, +mouse clicks can be used to place the cursor, set the mark (with two +clicks), and execute shortcuts. The mouse works in the X Window +System, and on the console when gpm is running. Text can still be +selected through dragging by holding down the Shift key. +.TP +.B set multibuffer +When reading in a file with \fB^R\fR, insert it into a new buffer by default. +.TP +.B set noconvert +Don't convert files from DOS/Mac format. +.TP +.B set nohelp +Don't display the two help lines at the bottom of the screen. +.TP +.B set nonewlines +Don't automatically add a newline when a text does not end with one. +(This can cause you to save non-POSIX text files.) +.TP +.B set nowrap +Deprecated option since it has become the default setting. +When needed, use \fBunset breaklonglines\fR instead. +.TP +.B set numbercolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for line numbers. +See \fBset titlecolor\fR for more details. +.TP +.B set operatingdir "\fIdirectory\fP" +\fBnanofur\fP only reads and writes files inside \fIdirectory\fP and its +subdirectories. Also, the current directory is changed to here, so +files are inserted from this directory. By default, the operating +directory feature is turned off. +.TP +.B set positionlog +Save the cursor position of files between editing sessions. +The cursor position is remembered for the 200 most-recently edited files. +.TP +.B set preserve +Preserve the XOFF and XON sequences (\fB^S\fR and \fB^Q\fR) so that +they are caught by the terminal (stopping and resuming the output). +.TP +.B set promptcolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the prompt bar. +(When this option is not specified, the colors of the title bar are used.) +See \fBset titlecolor\fR for more details. +.TP +.BI "set punct """ characters """ +Set the characters treated as closing punctuation when justifying +paragraphs. This may not include blank characters. Only the +specified closing punctuation, optionally followed by closing brackets +(see \fBbrackets\fP), can end sentences. The default value is "\fB!.?\fP". +.TP +.B set quickblank +Make status-bar messages disappear after 1 keystroke instead of after 20. +Note that option \fBconstantshow\fR overrides this. +When option \fBminibar\fR or \fBzero\fR is in effect, +\fBquickblank\fR makes a message disappear after +0.8 seconds instead of after the default 1.5 seconds. +.TP +.BI "set quotestr """ regex """ +Set the regular expression for matching the quoting part of a line. +The default value is "\fB^([\ \\t]*([!#%:;>|}]|//))+\fP". +(Note that \fB\\t\fR stands for an actual Tab character.) +This makes it possible to rejustify blocks of quoted text when composing +email, and to rewrap blocks of line comments when writing source code. +.TP +.B set rawsequences +Interpret escape sequences directly, instead of asking \fBncurses\fR +to translate them. (If you need this option to get some keys to work +properly, it means that the \fBterminfo\fR terminal description that is used +does not fully match the actual behavior of your terminal. This can +happen when you ssh into a BSD machine, for example.) +Using this option disables \fBnanofur\fR's mouse support. +.TP +.B set rebinddelete +Interpret the Delete and Backspace keys differently so that both Backspace +and Delete work properly. You should only use this option when on your +system either Backspace acts like Delete or Delete acts like Backspace. +.TP +.B set regexp +Do regular-expression searches by default. +Regular expressions in \fBnanofur\fR are of the extended type (ERE). +.TP +.B set saveonexit +Save a changed buffer automatically on exit (\fB^X\fR); don't prompt. +.TP +.B set scrollercolor \fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the indicator alias "scrollbar". +See \fBset titlecolor\fR for more details. +.TP +.B set selectedcolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for selected text. +See \fBset titlecolor\fR for more details. +.TP +.B set showcursor +Put the cursor on the highlighted item in the file browser, and show +the cursor in the help viewer, to aid braille users and people with +poor vision. +.TP +.B set smarthome +Make the Home key smarter. When Home is pressed anywhere but at the +very beginning of non-whitespace characters on a line, the cursor jumps +to that beginning (either forwards or backwards). If the cursor is +already at that position, it jumps to the true beginning of the line. +.TP +.B set softwrap +Display lines that exceed the screen's width over multiple screen lines. +(You can make this soft-wrapping occur at whitespace instead of rudely at +the screen's edge, by using also \fBset atblanks\fR.) +.TP +.B set speller """\fIprogram\fR [\fIargument \fR...]\fB""" +Use the given \fIprogram\fR to do spell checking and correcting, instead of +using the built-in corrector that calls \fBhunspell\fR(1) or \fBspell\fR(1). +.TP +.B set spotlightcolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for highlighting a search match. +The default value is \fBblack,lightyellow\fR. +See \fBset titlecolor\fR for valid color names. +.TP +.B set stateflags +Use the top-right corner of the screen for showing some state flags: +\fBI\fR when auto-indenting, \fBM\fR when the mark is on, \fBL\fR when +hard-wrapping (breaking long lines), \fBR\fR when recording a macro, +and \fBS\fR when soft-wrapping. +When the buffer is modified, a star (\fB*\fR) is shown after the +filename in the center of the title bar. +.TP +.B set statuscolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the status bar. +See \fBset titlecolor\fR for more details. +.TP +.B set stripecolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the vertical guiding stripe. +See \fBset titlecolor\fR for more details. +.TP +.B set tabsize \fInumber\fR +Use a tab size of \fInumber\fR columns. The value of \fInumber\fP must be +greater than 0. The default value is \fB8\fR. +.TP +.B set tabstospaces +Convert each typed tab to spaces -- to the number of spaces +that a tab at that position would take up. +(Note: pasted tabs are not converted.) +.TP +.B set titlecolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR +Use this color combination for the title bar. +Valid names for the foreground and background colors are: +.BR red ", " green ", " blue ", " magenta ", " yellow ", " cyan ", " +.BR white ", and " black . +Each of these eight names may be prefixed with the word \fBlight\fR +to get a brighter version of that color. +The word \fBgrey\fR or \fBgray\fR may be used +as a synonym for \fBlightblack\fR. +On a Linux console, \fBlight\fR does not have +any effect for a background color. +On terminal emulators that can do at least 256 colors, +other valid (but unprefixable) color names are: +.BR pink ", " purple ", " mauve ", " lagoon ", " mint ", " +.BR lime ", " peach ", " orange ", " latte ", " +.BR rosy ", " beet ", " plum ", " sea ", " sky ", " slate ", " +.BR teal ", " sage ", " brown ", " ocher ", " sand ", " tawny ", " +.BR brick ", " crimson ", and " normal +-- where \fBnormal\fR means the default foreground or background color. +On such emulators, the color may also be specified as a three-digit hexadecimal +number prefixed with \fB#\fR, with the digits representing the amounts of red, +green, and blue, respectively. This tells \fBnanofur\fR to select from the +available palette the color that approximates the given values. + +Either "\fIfgcolor\fR" or "\fB,\fIbgcolor\fR" may be left out, +and the pair may be preceded by \fBbold\fR and/or \fBitalic\fR +(separated by commas) to get a bold and/or slanting typeface, +if your terminal can do those. +.TP +.B set trimblanks +Remove trailing whitespace from wrapped lines when automatic +hard-wrapping occurs or when text is justified. +.TP +.B set unix +Save a file by default in Unix format. This overrides nanofur's +default behavior of saving a file in the format that it had. +(This option has no effect when you also use \fBset noconvert\fR.) +.TP +.BI "set whitespace """ characters """ +Set the two characters used to indicate the presence of tabs and +spaces. They must be single-column characters. The default pair +for a UTF-8 locale is "\fB\[Fc]\[md]\fR", and for other locales "\fB>.\fR". +.TP +.B set wordbounds +Detect word boundaries differently by treating punctuation +characters as parts of words. +.TP +.BI "set wordchars """ characters """ +Specify which other characters (besides the normal alphanumeric ones) +should be considered as parts of words. When using this option, you +probably want to unset \fBwordbounds\fR. +.TP +.B set zap +Let an unmodified Backspace or Delete erase the marked region +(instead of a single character, and without affecting the cutbuffer). +.TP +.B set zero +Hide all elements of the interface (title bar, status bar, and help lines) +and use all rows of the terminal for showing the contents of the buffer. +The status bar appears only when there is a significant message, +and disappears after 1.5 seconds or upon the next keystroke. +With \fBM\-Z\fR the title bar plus status bar can be toggled. +With \fBM\-X\fR the help lines. + +.SH SYNTAX HIGHLIGHTING +Coloring the different syntactic elements of a file +is done via regular expressions (see the \fBcolor\fR command below). +This is inherently imperfect, because regular expressions are not +powerful enough to fully parse a file. Nevertheless, regular +expressions can do a lot and are easy to make, so they are a +good fit for a small editor like \fBnanofur\fR. +.sp +All regular expressions in \fBnanofur\fR are POSIX extended regular expressions. +This means that \fB.\fR, \fB?\fR, \fB*\fR, \fB+\fR, \fB^\fR, \fB$\fR, and +several other characters are special. +The period \fB.\fR matches any single character, +\fB?\fR means the preceding item is optional, +\fB*\fR means the preceding item may be matched zero or more times, +\fB+\fR means the preceding item must be matched one or more times, +\fB^\fR matches the beginning of a line, and \fB$\fR the end, +\fB\\<\fR matches the start of a word, and \fB\\>\fR the end, +and \fB\\s\fR matches a blank. +It also means that lookahead and lookbehind are not possible. +A complete explanation can be found in the manual page of GNU grep: +\fBman grep\fR. +.sp +Each regular expression in a \fBnanofurrc\fR file should be wrapped in +double quotes (\fB""\fR). Multiple regular expressions can follow +each other on a line by separating them with blanks. This means that +a regular expression cannot contain a double quote followed by a blank. +When you need this combination inside a regular expression, +then either the double quote or the blank should be put +between square brackets (\fB[]\fR). +.sp +For each kind of file a separate syntax can be defined +via the following commands: +.TP +.BI syntax " name \fR[" """" fileregex """ " \fR...] +Start the definition of a syntax with this \fIname\fR. +All subsequent \fBcolor\fR and other such commands +are added to this syntax, until a new \fBsyntax\fR +command is encountered. +.sp +When \fBnanofur\fR is run, this syntax is automatically +activated (for the relevant buffer) if the absolute filename +matches the extended regular expression \fIfileregex\fR. +Or the syntax can be explicitly activated (for all buffers) +by using the \fB\-Y\fR or \fB\-\-syntax\fR +command-line option followed by the \fIname\fR. +.sp +The syntax \fBdefault\fP is special: it takes no \fIfileregex\fR, +and applies to files that don't match any syntax's regexes. +The syntax \fBnone\fP is reserved; specifying it on the command line +is the same as not having a syntax at all. +.TP +.BI "header """ regex """ \fR... +If from all defined syntaxes no \fIfileregex\fR matched, then compare +this \fIregex\fR (or regexes) against the first line of the current file, +to determine whether this syntax should be used for it. +.TP +.BI "magic """ regex """ \fR... +If no \fIfileregex\fR matched and no \fBheader\fR regex matched +either, then compare this \fIregex\fR (or regexes) against the +result of querying the \fBmagic\fP database about the current +file, to determine whether this syntax should be used for it. +(This querying is done only when \fBlibmagic\fR is actually installed +on the system and \fB\-\-magic\fR or \fBset magic\fR was given.) +.TP +.BI formatter " program " \fR[ "argument " \fR...] +Run the given \fIprogram\fR on the full contents of the current buffer. +.TP +.BI linter " program " \fR[ "argument " \fR...] +Use the given \fIprogram\fR to run a syntax check on the current buffer. +.TP +.BI "comment """ string """ +Use the given \fIstring\fR for commenting and uncommenting lines. +If the string contains a vertical bar or pipe character (\fB|\fR), +this designates bracket-style comments; for example, "\fB/*|*/\fR" for +CSS files. The characters before the pipe are prepended to the line and the +characters after the pipe are appended at the end of the line. If no pipe +character is present, the full string is prepended; for example, "\fB#\fR" +for Python files. If empty double quotes are specified, the comment/uncomment +function is disabled; for example, "" for JSON. +The default value is "\fB#\fP". +.TP +.BI "tabgives """ string """ +Make the key produce the given \fIstring\fR. Useful for languages like +Python that want to see only spaces for indentation. +This overrides the setting of the \fBtabstospaces\fR option. +.TP +.BI "color \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " """ regex """ " \fR... +Paint all pieces of text that match the extended regular expression +\fIregex\fP with the given foreground and background colors, at least +one of which must be specified. Valid color names are: +.BR red ", " green ", " blue ", " magenta ", " yellow ", " cyan ", " +.BR white ", and " black . +Each of these eight names may be prefixed with the word \fBlight\fR +to get a brighter version of that color. +The word \fBgrey\fR or \fBgray\fR may be used +as a synonym for \fBlightblack\fR. +On a Linux console, \fBlight\fR does not have +any effect for a background color. +On terminal emulators that can do at least 256 colors, +other valid (but unprefixable) color names are: +.BR pink ", " purple ", " mauve ", " lagoon ", " mint ", " +.BR lime ", " peach ", " orange ", " latte ", " +.BR rosy ", " beet ", " plum ", " sea ", " sky ", " slate ", " +.BR teal ", " sage ", " brown ", " ocher ", " sand ", " tawny ", " +.BR brick ", " crimson ", and " normal +-- where \fBnormal\fR means the default foreground or background color. +On such emulators, the color may also be specified as a three-digit hexadecimal +number prefixed with \fB#\fR, with the digits representing the amounts of red, +green, and blue, respectively. This tells \fBnanofur\fR to select from the +available palette the color that approximates the given values. + +The color pair may be preceded by \fBbold\fR and/or \fBitalic\fR +(separated by commas) to get a bold and/or slanting typeface, +if your terminal can do those. +.sp +All coloring commands are applied in the order in which they are specified, +which means that later commands can recolor stuff that was colored earlier. +.TP +.BI "icolor \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " """ regex """ " \fR... +Same as above, except that the matching is case insensitive. +.TP +.BI "color \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " start=""" fromrx """ end=""" torx """ +Paint all pieces of text whose start matches extended regular expression +\fIfromrx\fP and whose end matches extended regular expression \fItorx\fP +with the given foreground and background colors, +at least one of which must be specified. This means that, after an +initial instance of \fIfromrx\fP, all text until the first instance of +\fItorx\fP is colored. This allows syntax highlighting to span +multiple lines. +.TP +.BI "icolor \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " start=""" fromrx """ end=""" torx """ +Same as above, except that the matching is case insensitive. +.TP +.BI "include """ syntaxfile """ +Read in self-contained color syntaxes from \fIsyntaxfile\fP. Note that +\fIsyntaxfile\fP may contain only the above commands, from \fBsyntax\fP +to \fBicolor\fP. +.TP +.BI extendsyntax " name command argument " \fR... +Extend the syntax previously defined as \fIname\fR with another +\fIcommand\fR. This allows adding a new \fBcolor\fP, \fBicolor\fP, +\fBheader\fR, \fBmagic\fR, \fBformatter\fR, \fBlinter\fR, \fBcomment\fR, +or \fBtabgives\fR +command to an already defined syntax -- useful when you want to +slightly improve a syntax defined in one of the system-installed +files (which normally are not writable). + +.SH REBINDING KEYS +Key bindings can be changed via the following three commands: +.RS 3 +.TP +.BI bind " key function menu" +Rebinds the given \fIkey\fP to the given \fIfunction\fP in the given \fImenu\fP +(or in all menus where the function exists when \fBall\fP is used). +.TP +.BI bind " key " """" string """" " menu" +Makes the given \fIkey\fR produce the given \fIstring\fR in the given +\fImenu\fR (or in all menus where the key exists when \fBall\fR is used). +Besides literal text and/or control codes, the \fIstring\fR may contain +function names between braces. These functions are invoked when +the key is typed. To include a literal opening brace, use \fB{{}\fR. +.TP +.BI unbind " key menu" +Unbinds the given \fIkey\fP from the given \fImenu\fP (or from all +menus where the key exists when \fBall\fP is used). +.RE +.sp +Note that \fBbind \fIkey\fR \fB"{\fIfunction\fB}"\fR \fImenu\fR is equivalent +to \fBbind \fIkey\fR \fIfunction\fR \fImenu\fR, except that for the latter form +\fBnanofur\fR checks the availability of the \fIfunction\fR in the given \fImenu\fR +at startup time (and reports an error if it does not exist there), whereas for the +first form \fBnanofur\fR checks at execution time that the \fIfunction\fR exists +but not whether it makes any sense in the current menu. The user has to take care +that a function name between braces (or any sequence of them) is appropriate. +Strange behavior or even a crash can result when the braced name is unfitting. + +.TP +The format of \fIkey\fP should be one of: +.RS 3 +.TP 7 +.BI ^ X +where \fIX\fR is a Latin letter, or one of several ASCII characters +(@, ], \\, ^, _), or the word "Space". +Example: ^C. +.TP +.BI M\- X +where \fIX\fR is any ASCII character except [, or the word "Space". +Example: M\-8. +.TP +.BI Sh\-M\- X +where \fIX\fR is a Latin letter. +Example: Sh\-M\-U. +By default, each Meta+letter keystroke does the same as the corresponding +Shift+Meta+letter. But when any Shift+Meta bind is made, that will +no longer be the case, for all letters. +.TP +.BI F N +where \fIN\fR is a numeric value from 1 to 24. +Example: F10. +(Often, \fBF13\fR to \fBF24\fR can be typed as \fBF1\fR to \fBF12\fR with Shift.) +.TP +.BR Ins " or " Del . +.RE +.sp +Rebinding \fB^M\fR (Enter) or \fB^I\fR (Tab) is probably not a good idea. +Rebinding \fB^[\fR (Esc) is not possible, because its keycode +is the starter byte of Meta keystrokes and escape sequences. +Rebinding any of the dedicated cursor-moving keys (the arrows, +Home, End, PageUp and PageDown) is not possible. +On some terminals it's not possible to rebind \fB^H\fR (unless \fB\-\-raw\fR +is used) because its keycode is identical to that of the Backspace key. + +.TP +Valid \fIfunction\fP names to be bound are: +.RS 3 +.TP 2 +.B help +Invokes the help viewer. +.TP +.B cancel +Cancels the current command. +.TP +.B exit +Exits from the program (or from the help viewer or file browser). +.TP +.B writeout +Writes the current buffer to disk, asking for a name. +.TP +.B savefile +Writes the current file to disk without prompting. +.TP +.B insert +Inserts a file into the current buffer (at the current cursor position), +or into a new buffer when option \fBmultibuffer\fR is set. +.TP +.B whereis +Starts a forward search for text in the current buffer -- or for filenames +matching a string in the current list in the file browser. +.TP +.B wherewas +Starts a backward search for text in the current buffer -- or for filenames +matching a string in the current list in the file browser. +.TP +.B findprevious +Searches the next occurrence in the backward direction. +.TP +.B findnext +Searches the next occurrence in the forward direction. +.TP +.B replace +Interactively replaces text within the current buffer. +.TP +.B cut +Cuts and stores the current line (or the marked region). +.TP +.B copy +Copies the current line (or the marked region) without deleting it. +.TP +.B paste +Pastes the currently stored text into the current buffer at the +current cursor position. +.TP +.B zap +Throws away the current line (or the marked region). +(This function is bound by default to .) +.TP +.B chopwordleft +Deletes from the cursor position to the beginning of the preceding word. +(This function is bound by default to . If your terminal +produces \fB^H\fR for , you can make delete +the word to the left of the cursor by rebinding \fB^H\fR to this function.) +.TP +.B chopwordright +Deletes from the cursor position to the beginning of the next word. +(This function is bound by default to .) +.TP +.B cutrestoffile +Cuts all text from the cursor position till the end of the buffer. +.TP +.B mark +Sets the mark at the current position, to start selecting text. +Or, when it is set, unsets the mark. +.TP +.B location +Reports the current position of the cursor in the buffer: +the line, column, and character positions. +.TP +.B wordcount +Counts and reports on the status bar the number of lines, words, +and characters in the current buffer (or in the marked region). +.TP +.B execute +Prompts for a program to execute. The program's output is inserted +into the current buffer (or into a new buffer when \fBM\-F\fR is toggled). +.TP +.B speller +Invokes a spell-checking program, either the default \fBhunspell\fR(1) or GNU +\fBspell\fR(1), or the one defined by \fB\-\-speller\fR or \fBset speller\fR. +.TP +.B formatter +Invokes a full-buffer-processing program (if the active syntax defines one). +(The current buffer is written out to a temporary file, the program +is run on it, and then the temporary file is read back in, replacing +the contents of the buffer.) +.TP +.B linter +Invokes a syntax-checking program (if the active syntax defines one). +If this program produces lines of the form "filename:linenum:charnum: +some message", then the cursor is put at the indicated position +in the mentioned file while showing "some message" on the status bar. +You can move from message to message with and , +and leave linting mode with \fB^C\fR or . +.TP +.B justify +Justifies the current paragraph (or the marked region). +A paragraph is a group of contiguous lines that, apart from possibly +the first line, all have the same indentation. The beginning of a +paragraph is detected by either this lone line with a differing +indentation or by a preceding blank line. +.TP +.B fulljustify +Justifies the entire current buffer (or the marked region). +.TP +.B indent +Indents (shifts to the right) the current line or the marked lines. +.TP +.B unindent +Unindents (shifts to the left) the current line or the marked lines. +.TP +.B comment +Comments or uncomments the current line or the marked lines, +using the comment style specified in the active syntax. +.TP +.B complete +Completes (when possible) the fragment before the cursor +to a full word found elsewhere in the current buffer. +.TP +.B left +Goes left one position (in the editor or browser). +.TP +.B right +Goes right one position (in the editor or browser). +.TP +.B up +Goes one line up (in the editor or browser). +.TP +.B down +Goes one line down (in the editor or browser). +.TP +.B scrollup +Scrolls the viewport up one row (meaning that the text slides down) +while keeping the cursor in the same text position, if possible. +(This function is bound by default to . +If does nothing on your Linux console, see the FAQ: +.UR https://nanofur\-editor.org/dist/latest/faq.html#4.1 +.UE .) +.TP +.B scrolldown +Scrolls the viewport down one row (meaning that the text slides up) +while keeping the cursor in the same text position, if possible. +(This function is bound by default to .) +.TP +.B center +Scrolls the line with the cursor to the middle of the viewport. +.TP +.B cycle +Scrolls the line with the cursor first to the middle of the viewport, +then to the top, then to the bottom. +.TP +.B prevword +Moves the cursor to the beginning of the previous word. +.TP +.B nextword +Moves the cursor to the beginning of the next word. +.TP +.B home +Moves the cursor to the beginning of the current line. +.TP +.B end +Moves the cursor to the end of the current line. +.TP +.B beginpara +Moves the cursor to the beginning of the current paragraph. +.TP +.B endpara +Moves the cursor to the end of the current paragraph. +.TP +.B prevblock +Moves the cursor to the beginning of the current or preceding block of text. +(Blocks are separated by one or more blank lines.) +.TP +.B nextblock +Moves the cursor to the beginning of the next block of text. +.TP +.B toprow +Moves the cursor to the first row in the viewport. +.TP +.B bottomrow +Moves the cursor to the last row in the viewport. +.TP +.B pageup +Goes up one screenful. +.TP +.B pagedown +Goes down one screenful. +.TP +.B firstline +Goes to the first line of the file. +.TP +.B lastline +Goes to the last line of the file. +.TP +.B gotoline +Goes to a specific line (and column if specified). Negative numbers count +from the end of the file (and end of the line). +.TP +.B findbracket +Moves the cursor to the bracket (or brace or parenthesis, etc.) that matches +(pairs) with the one under the cursor. See \fBset matchbrackets\fR. +.TP +.B anchor +Places an anchor at the current line, or removes it when already present. +(An anchor is visible when line numbers are activated.) +.TP +.B prevanchor +Goes to the first anchor before the current line. +.TP +.B nextanchor +Goes to the first anchor after the current line. +.TP +.B prevbuf +Switches to editing/viewing the previous buffer when multiple buffers are open. +.TP +.B nextbuf +Switches to editing/viewing the next buffer when multiple buffers are open. +.TP +.B verbatim +Inserts the next keystroke verbatim into the file, or begins Unicode input +when a hexadecimal digit is typed. +.TP +.B tab +Inserts a tab at the current cursor location. +.TP +.B enter +Inserts a new line below the current one. +.TP +.B delete +Deletes the character under the cursor. +.TP +.B backspace +Deletes the character before the cursor. +.TP +.B recordmacro +Starts the recording of keystrokes -- the keystrokes are stored +as a macro. When already recording, the recording is stopped. +.TP +.B runmacro +Replays the keystrokes of the last recorded macro. +.TP +.B undo +Undoes the last performed text action (add text, delete text, etc). +.TP +.B redo +Redoes the last undone action (i.e., it undoes an undo). +.TP +.B refresh +Refreshes the screen. +.TP +.B suspend +Suspends the editor and returns control to the shell +(until you tell the process to resume execution with \fBfg\fR). +.TP +.B casesens +Toggles whether searching/replacing ignores or respects the case of +the given characters. +.TP +.B regexp +Toggles whether searching/replacing uses literal strings or regular expressions. +.TP +.B backwards +Toggles whether searching/replacing goes forward or backward. +.TP +.B older +Retrieves the previous (earlier) entry at a prompt. +.TP +.B newer +Retrieves the next (later) entry at a prompt. +.TP +.B flipreplace +Toggles between searching for something and replacing something. +.TP +.B flipgoto +Toggles between searching for text and targeting a line number. +.TP +.B flipexecute +Switches from inserting a file to executing a command. +.TP +.B flippipe +When executing a command, toggles whether the current buffer (or marked +region) is piped to the command. +.TP +.B flipnewbuffer +Toggles between inserting into the current buffer and into a new +empty buffer. +.TP +.B flipconvert +When reading in a file, toggles between converting and not converting +it from DOS/Mac format. Converting is the default. +.TP +.B dosformat +When writing a file, switches to writing a DOS format (CR/LF). +.TP +.B macformat +When writing a file, switches to writing a Mac format. +.TP +.B append +When writing a file, appends to the end instead of overwriting. +.TP +.B prepend +When writing a file, 'prepends' (writes at the beginning) instead of overwriting. +.TP +.B backup +When writing a file, creates a backup of the current file. +.TP +.B discardbuffer +When about to write a file, discard the current buffer without saving. +(This function is bound by default only when option \fB\-\-saveonexit\fR +is in effect.) +.TP +.B browser +Starts the file browser (in the Read File and Write Out menus), +allowing to select a file from a list. +.TP +.B gotodir +Goes to a directory to be specified, allowing to browse anywhere +in the filesystem. +.TP +.B firstfile +Goes to the first file in the list when using the file browser. +.TP +.B lastfile +Goes to the last file in the list when using the file browser. +.TP +.B nohelp +Toggles the presence of the two-line list of key bindings at the bottom of the screen. +(This toggle is special: it is available in all menus except the help viewer +and the linter. All further toggles are available in the main menu only.) +.TP +.B zero +Toggles the presence of title bar and status bar. +.TP +.B constantshow +Toggles the constant display of the current line, column, and character positions. +.TP +.B softwrap +Toggles the displaying of overlong lines on multiple screen lines. +.TP +.B linenumbers +Toggles the display of line numbers in front of the text. +.TP +.B whitespacedisplay +Toggles the showing of whitespace. +.TP +.B nosyntax +Toggles syntax highlighting. +.TP +.B smarthome +Toggles the smartness of the Home key. +.TP +.B autoindent +Toggles whether a newly created line will contain the same amount of leading +whitespace as the preceding line -- or as the next line if the preceding line +is the beginning of a paragraph. +.TP +.B cutfromcursor +Toggles whether cutting text cuts the whole line or just from the current cursor +position to the end of the line. +.TP +.B breaklonglines +Toggles whether the overlong part of a line is hard-wrapped to the next line. +.TP +.B tabstospaces +Toggles whether typed tabs are converted to spaces. +.TP +.B mouse +Toggles mouse support. +.RE + +.TP +Valid \fImenu\fP sections are: +.RS 3 +.TP 2 +.B main +The main editor window where text is entered and edited. +.TP +.B help +The help-viewer menu. +.TP +.B search +The search menu (AKA whereis). +.TP +.B replace +The 'search to replace' menu. +.TP +.B replacewith +The 'replace with' menu, which comes up after 'search to replace'. +.TP +.B yesno +The 'yesno' menu, where the Yes/No/All/Cancel question is asked. +.TP +.B gotoline +The 'goto line (and column)' menu. +.TP +.B writeout +The 'write file' menu. +.TP +.B insert +The 'insert file' menu. +.TP +.B browser +The 'file browser' menu, for selecting a file to be opened or +inserted or written to. +.TP +.B whereisfile +The 'search for a file' menu in the file browser. +.TP +.B gotodir +The 'go to directory' menu in the file browser. +.TP +.B execute +The menu for inserting the output from an external command, +or for filtering the buffer (or the marked region) through +an external command, or for executing one of several tools. +.TP +.B spell +The menu of the integrated spell checker where the user can edit a misspelled word. +.TP +.B linter +The linter menu, which allows jumping through the linting messages. +.TP +.B all +A special name that encompasses all menus. +For \fBbind\fR it means all menus where the specified \fIfunction\fR exists; +for \fBunbind\fR it means all menus where the specified \fIkey\fR exists. +.RE + +.SH EXAMPLES +To make \fBCtrl+Z\fR suspend nanofur: +.sp +.RS +.B bind ^Z suspend main +.RE +.sp +To make \fBShift+Alt+C\fR copy the marked region to the system's clipboard: +.sp +.RS +.B bind Sh-M-C """{execute}| xsel -ib {enter}{undo}""" main +.RE +.sp + +.SH FILES +.TP +.I /etc/nanofurrc +System-wide configuration file. +.TP +.IR ~/.nanofurrc " or " $XDG_CONFIG_HOME/nanofur/nanofurrc " or " ~/.config/nanofur/nanofurrc +Per-user configuration file. +.TP +.I /usr/share/nanofur/* +Syntax definitions for the syntax coloring of common file types +(and for less common file types in the \fIextra/\fR subdirectory). + +.SH SEE ALSO +.BR nanofur (1) +.TP +.I https://nanofur-editor.org/cheatsheet.html +An overview of the default key bindings. diff --git a/doc/rnanofur.1 b/doc/rnanofur.1 new file mode 100644 index 0000000..009c01d --- /dev/null +++ b/doc/rnanofur.1 @@ -0,0 +1,64 @@ +.\" Copyright (C) 2002-2007, 2014-2024 Free Software Foundation, Inc. +.\" +.\" This document is dual-licensed. You may distribute and/or modify it +.\" under the terms of either of the following licenses: +.\" +.\" * The GNU General Public License, as published by the Free Software +.\" Foundation, version 3 or (at your option) any later version. You +.\" should have received a copy of the GNU General Public License +.\" along with this program. If not, see +.\" . +.\" +.\" * The GNU Free Documentation License, as published by the Free +.\" Software Foundation, version 1.2 or (at your option) any later +.\" version, with no Invariant Sections, no Front-Cover Texts, and no +.\" Back-Cover Texts. You should have received a copy of the GNU Free +.\" Documentation License along with this program. If not, see +.\" . +.\" +.TH RNANOFUR 1 "version 8.2" "September 2024" + +.SH NAME +rnanofur \- a restricted nanofur + +.SH SYNOPSIS +.B rnanofur +.RI [ options "] [[+" line [, column "]]\ " file "]..." + +.SH DESCRIPTION +\fBrnanofur\fR runs the \fBnanofur\fR editor in restricted mode. This allows +editing only the specified file or files, and doesn't allow the user +access to the filesystem nor to a command shell. +.sp +In restricted mode, \fBnanofur\fR will: +.IP \[bu] 2 +not make backups; +.IP \[bu] +not allow suspending; +.IP \[bu] +not allow spell checking; +.IP \[bu] +not read nor write the history files; +.IP \[bu] +not allow saving the current buffer under a different name; +.IP \[bu] +not allow inserting another file or opening a new buffer; +.IP \[bu] +not allow appending or prepending to any file. + +.SH OPTIONS +.TP +.BR \-h ", " \-\-help +Show the available command-line options and exit. +.P +For all existing options, see the \fBnanofur\fR(1) man page. + +.SH BUGS +Please report bugs via +.IR https://savannah.gnu.org/bugs/?group=nanofur . + +.SH HOMEPAGE +.I https://nanofur-editor.org/ + +.SH SEE ALSO +.BR nanofur (1) diff --git a/doc/sample.nanofurrc.in b/doc/sample.nanofurrc.in new file mode 100644 index 0000000..5dc1a9a --- /dev/null +++ b/doc/sample.nanofurrc.in @@ -0,0 +1,341 @@ +## Sample initialization file for GNU nanofur. +## +## For the options that take parameters, the default value is shown. +## Other options are unset by default. To make sure that an option +## is disabled, you can use "unset