# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR Free Software Foundation, Inc. # This file is distributed under the same license as the PACKAGE package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "POT-Creation-Date: 2021-11-07 12:11+0900\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <LL@li.org>\n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: node #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:6 #, no-wrap msgid "Tips" msgstr "" #. type: appendix #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:7 #, no-wrap msgid "Tips and Conventions" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:8 #, no-wrap msgid "tips for writing Lisp" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:9 #, no-wrap msgid "standards of coding style" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:10 #, no-wrap msgid "coding standards" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:11 #, no-wrap msgid "best practices" msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:17 msgid "" "This chapter describes no additional features of Emacs Lisp. Instead it " "gives advice on making effective use of the features described in the " "previous chapters, and describes conventions Emacs Lisp programmers should " "follow." msgstr "" #. type: findex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:18 #, no-wrap msgid "checkdoc" msgstr "" #. type: findex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:19 #, no-wrap msgid "checkdoc-current-buffer" msgstr "" #. type: findex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:20 #, no-wrap msgid "checkdoc-file" msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:30 msgid "" "You can automatically check some of the conventions described below by " "running the command @kbd{M-x checkdoc @key{RET}} when visiting a Lisp file. " "It cannot check all of the conventions, and not all the warnings it gives " "necessarily correspond to problems, but it is worth examining them all. " "Alternatively, use the command @kbd{M-x checkdoc-current-buffer @key{RET}} " "to check the conventions in the current buffer, or @code{checkdoc-file} when " "you want to check a file in batch mode, e.g., with a command run by " "@kbd{@w{M-x compile @key{RET}}}." msgstr "" #. type: node #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 /Users/suzume/Documents/Repositories/Projet #: OmegaT de Documentation Emacs - Sources/doc/lispref/tips.texi:42 #, no-wrap msgid "Coding Conventions" msgstr "" #. type: menuentry #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 msgid "Conventions for clean and robust programs." msgstr "" #. type: section #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 /Users/suzume/Documents/Repositories/Projet #: OmegaT de Documentation Emacs - Sources/doc/lispref/tips.texi:257 #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:258 #, no-wrap msgid "Key Binding Conventions" msgstr "" #. type: menuentry #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 msgid "Which keys should be bound by which programs." msgstr "" #. type: node #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 /Users/suzume/Documents/Repositories/Projet #: OmegaT de Documentation Emacs - Sources/doc/lispref/tips.texi:338 #, no-wrap msgid "Programming Tips" msgstr "" #. type: menuentry #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 msgid "Making Emacs code fit smoothly in Emacs." msgstr "" #. type: node #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 /Users/suzume/Documents/Repositories/Projet #: OmegaT de Documentation Emacs - Sources/doc/lispref/tips.texi:469 #, no-wrap msgid "Compilation Tips" msgstr "" #. type: menuentry #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 msgid "Making compiled code run fast." msgstr "" #. type: node #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 /Users/suzume/Documents/Repositories/Projet #: OmegaT de Documentation Emacs - Sources/doc/lispref/tips.texi:524 #, no-wrap msgid "Warning Tips" msgstr "" #. type: menuentry #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 msgid "Turning off compiler warnings." msgstr "" #. type: node #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 /Users/suzume/Documents/Repositories/Projet #: OmegaT de Documentation Emacs - Sources/doc/lispref/tips.texi:578 #, no-wrap msgid "Documentation Tips" msgstr "" #. type: menuentry #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 msgid "Writing readable documentation strings." msgstr "" #. type: node #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 /Users/suzume/Documents/Repositories/Projet #: OmegaT de Documentation Emacs - Sources/doc/lispref/tips.texi:894 #, no-wrap msgid "Comment Tips" msgstr "" #. type: menuentry #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 msgid "Conventions for writing comments." msgstr "" #. type: node #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 /Users/suzume/Documents/Repositories/Projet #: OmegaT de Documentation Emacs - Sources/doc/lispref/tips.texi:1008 #, no-wrap msgid "Library Headers" msgstr "" #. type: menuentry #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:40 msgid "Standard headers for library packages." msgstr "" #. type: section #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:43 #, no-wrap msgid "Emacs Lisp Coding Conventions" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:45 #, no-wrap msgid "coding conventions in Emacs Lisp" msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:48 msgid "" "Here are conventions that you should follow when writing Emacs Lisp code " "intended for widespread use:" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:54 msgid "" "Simply loading a package should not change Emacs's editing behavior. " "Include a command or commands to enable and disable the feature, or to " "invoke it." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:59 msgid "" "This convention is mandatory for any file that includes custom definitions. " "If fixing such a file to follow this convention requires an incompatible " "change, go ahead and make the incompatible change; don't postpone it." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:71 msgid "" "You should choose a short word to distinguish your program from other Lisp " "programs. The names of all global symbols in your program, that is the " "names of variables, constants, and functions, should begin with that chosen " "prefix. Separate the prefix from the rest of the name with a hyphen, " "@samp{-}. This practice helps avoid name conflicts, since all global " "variables in Emacs Lisp share the same name space, and all functions share " "another name space@footnote{The benefits of a Common Lisp-style package " "system are considered not to outweigh the costs.}. Use two hyphens to " "separate prefix and name if the symbol is not meant to be used by other " "packages." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:80 msgid "" "Occasionally, for a command name intended for users to use, it is more " "convenient if some words come before the package's name prefix. For " "example, it is our convention to have commands that list objects named as " "@samp{list-@var{something}}, e.g., a package called @samp{frob} could have a " "command @samp{list-frobs}, when its other global symbols begin with " "@samp{frob-}. Also, constructs that define functions, variables, etc., work " "better if they start with @samp{define-}, so put the name prefix later on in " "the name." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:87 msgid "" "This recommendation applies even to names for traditional Lisp primitives " "that are not primitives in Emacs Lisp---such as @code{copy-list}. Believe " "it or not, there is more than one plausible way to define @code{copy-list}. " "Play it safe; append your name prefix to produce a name like " "@code{foo-copy-list} or @code{mylib-copy-list} instead." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:93 msgid "" "If you write a function that you think ought to be added to Emacs under a " "certain name, such as @code{twiddle-files}, don't call it by that name in " "your program. Call it @code{mylib-twiddle-files} in your program, and send " "mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add it to Emacs. If and " "when we do, we can change the name easily enough." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:96 msgid "" "If one prefix is insufficient, your package can use two or three alternative " "common prefixes, so long as they make sense." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:101 msgid "" "We recommend enabling @code{lexical-binding} in new code, and converting " "existing Emacs Lisp code to enable @code{lexical-binding} if it doesn't " "already. @xref{Using Lexical Binding}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:105 msgid "" "Put a call to @code{provide} at the end of each separate Lisp file. " "@xref{Named Features}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:111 msgid "" "If a file requires certain other Lisp programs to be loaded beforehand, then " "the comments at the beginning of the file should say so. Also, use " "@code{require} to make sure they are loaded. @xref{Named Features}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:116 msgid "" "If a file @var{foo} uses a macro defined in another file @var{bar}, but does " "not use any functions or variables defined in @var{bar}, then @var{foo} " "should contain the following expression:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:119 #, no-wrap msgid "(eval-when-compile (require '@var{bar}))\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:128 msgid "" "This tells Emacs to load @var{bar} just before byte-compiling @var{foo}, so " "that the macro definition is available during compilation. Using " "@code{eval-when-compile} avoids loading @var{bar} when the compiled version " "of @var{foo} is @emph{used}. It should be called before the first use of " "the macro in the file. @xref{Compiling Macros}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:139 msgid "" "Avoid loading additional libraries at run time unless they are really " "needed. If your file simply cannot work without some other library, then " "just @code{require} that library at the top-level and be done with it. But " "if your file contains several independent features, and only one or two " "require the extra library, then consider putting @code{require} statements " "inside the relevant functions rather than at the top-level. Or use " "@code{autoload} statements to load the extra library when needed. This way " "people who don't use those aspects of your file do not need to load the " "extra library." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:144 msgid "" "If you need Common Lisp extensions, use the @code{cl-lib} library rather " "than the old @code{cl} library. The latter library is deprecated and will " "be removed in a future version of Emacs." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:148 msgid "" "When defining a major mode, please follow the major mode conventions. " "@xref{Major Mode Conventions}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:152 msgid "" "When defining a minor mode, please follow the minor mode conventions. " "@xref{Minor Mode Conventions}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:162 msgid "" "If the purpose of a function is to tell you whether a certain condition is " "true or false, give the function a name that ends in @samp{p} (which stands " "for ``predicate''). If the name is one word, add just @samp{p}; if the name " "is multiple words, add @samp{-p}. Examples are @code{framep} and " "@code{frame-live-p}. We recommend to avoid using this @code{-p} suffix in " "boolean variable names, unless the variable is bound to a predicate " "function; instead, use a @code{-flag} suffix or names like @code{is-foo}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:168 msgid "" "If the purpose of a variable is to store a single function, give it a name " "that ends in @samp{-function}. If the purpose of a variable is to store a " "list of functions (i.e., the variable is a hook), please follow the naming " "conventions for hooks. @xref{Hooks}." msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:170 #, no-wrap msgid "unloading packages, preparing for" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:177 msgid "" "Using @code{unload-feature} will undo the changes usually done by loading a " "feature (like adding functions to hooks). However, if loading @var{feature} " "does something unusual and more complex, you can define a function named " "@code{@var{feature}-unload-function}, and make it undo any such special " "changes. @code{unload-feature} will then automatically run this function if " "it exists. @xref{Unloading}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:183 msgid "" "It is a bad idea to define aliases for the Emacs primitives. Normally you " "should use the standard names instead. The case where an alias may be " "useful is where it facilitates backwards compatibility or portability." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:190 msgid "" "If a package needs to define an alias or a new function for compatibility " "with some other version of Emacs, name it with the package prefix, not with " "the raw name with which it occurs in the other version. Here is an example " "from Gnus, which provides many examples of such compatibility issues." msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:196 #, no-wrap msgid "" "(defalias 'gnus-point-at-bol\n" " (if (fboundp 'point-at-bol)\n" " 'point-at-bol\n" " 'line-beginning-position))\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:202 msgid "" "Redefining or advising an Emacs primitive is a bad idea. It may do the " "right thing for a particular program, but there is no telling what other " "programs might break as a result." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:206 msgid "" "It is likewise a bad idea for one Lisp package to advise a function in " "another Lisp package (@pxref{Advising Functions})." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:214 msgid "" "Avoid using @code{eval-after-load} and @code{with-eval-after-load} in " "libraries and packages (@pxref{Hooks for Loading}). This feature is meant " "for personal customizations; using it in a Lisp program is unclean, because " "it modifies the behavior of another Lisp file in a way that's not visible in " "that file. This is an obstacle for debugging, much like advising a function " "in the other package." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:220 msgid "" "If a file does replace any of the standard functions or library programs of " "Emacs, prominent comments at the beginning of the file should say which " "functions are replaced, and how the behavior of the replacements differs " "from that of the originals." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:228 msgid "" "Constructs that define a function or variable should be macros, not " "functions, and their names should start with @samp{define-}. The macro " "should receive the name to be defined as the first argument. That will help " "various tools find the definition automatically. Avoid constructing the " "names in the macro itself, since that would confuse these tools." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:235 msgid "" "In some other systems there is a convention of choosing variable names that " "begin and end with @samp{*}. We don't use that convention in Emacs Lisp, so " "please don't use it in your programs. (Emacs uses such names only for " "special-purpose buffers.) People will find Emacs more coherent if all " "libraries use the same conventions." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:243 msgid "" "The default file coding system for Emacs Lisp source files is UTF-8 " "(@pxref{Text Representations}). In the rare event that your program " "contains characters which are @emph{not} in UTF-8, you should specify an " "appropriate coding system in the source file's @samp{-*-} line or local " "variables list. @xref{File Variables, , Local Variables in Files, emacs, " "The GNU Emacs Manual}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:246 msgid "Indent the file using the default indentation parameters." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:250 msgid "" "Don't make a habit of putting close-parentheses on lines by themselves; Lisp " "programmers find this disconcerting." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:254 msgid "" "Please put a copyright notice and copying permission notice on the file if " "you distribute copies. @xref{Library Headers}." msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:259 #, no-wrap msgid "key binding, conventions for" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:263 #, no-wrap msgid "mouse-2" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:264 #, no-wrap msgid "references, following" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:272 msgid "" "Many special major modes, like Dired, Info, Compilation, and Occur, are " "designed to handle read-only text that contains @dfn{hyper-links}. Such a " "major mode should redefine @kbd{mouse-2} and @key{RET} to follow the links. " "It should also set up a @code{follow-link} condition, so that the link obeys " "@code{mouse-1-click-follows-link}. @xref{Clickable Text}. @xref{Buttons}, " "for an easy method of implementing such clickable links." msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:274 #, no-wrap msgid "reserved keys" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:275 #, no-wrap msgid "keys, reserved" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:281 msgid "" "Don't define @kbd{C-c @var{letter}} as a key in Lisp programs. Sequences " "consisting of @kbd{C-c} and a letter (either upper or lower case; " "@acronym{ASCII} or non-@acronym{ASCII}) are reserved for users; they are the " "@strong{only} sequences reserved for users, so do not block them." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:285 msgid "" "Changing all the Emacs major modes to respect this convention was a lot of " "work; abandoning this convention would make that work go to waste, and " "inconvenience users. Please comply with it." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:289 msgid "" "Function keys @key{F5} through @key{F9} without modifier keys are also " "reserved for users to define." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:293 msgid "" "Sequences consisting of @kbd{C-c} followed by a control character or a digit " "are reserved for major modes." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:297 msgid "" "Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}}, @kbd{<}, " "@kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:304 msgid "" "Sequences consisting of @kbd{C-c} followed by any other @acronym{ASCII} " "punctuation or symbol character are allocated for minor modes. Using them " "in a major mode is not absolutely prohibited, but if you do that, the major " "mode binding may be shadowed from time to time by minor modes." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:310 msgid "" "Don't bind @kbd{C-h} following any prefix character (including @kbd{C-c}). " "If you don't bind @kbd{C-h}, it is automatically available as a help " "character for listing the subcommands of the prefix character." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:315 msgid "" "Don't bind a key sequence ending in @key{ESC} except following another " "@key{ESC}. (That is, it is OK to bind a sequence ending in @kbd{@key{ESC} " "@key{ESC}}.)" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:319 msgid "" "The reason for this rule is that a non-prefix binding for @key{ESC} in any " "context prevents recognition of escape sequences as function keys in that " "context." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:323 msgid "" "Similarly, don't bind a key sequence ending in @kbd{C-g}, since that is " "commonly used to cancel a key sequence." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:328 msgid "" "Anything that acts like a temporary mode or state that the user can enter " "and leave should define @kbd{@key{ESC} @key{ESC}} or @kbd{@key{ESC} " "@key{ESC} @key{ESC}} as a way to escape." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:336 msgid "" "For a state that accepts ordinary Emacs commands, or more generally any kind " "of state in which @key{ESC} followed by a function key or arrow key is " "potentially meaningful, then you must not define @kbd{@key{ESC} @key{ESC}}, " "since that would preclude recognizing an escape sequence after @key{ESC}. " "In these states, you should define @kbd{@key{ESC} @key{ESC} @key{ESC}} as " "the way to escape. Otherwise, define @kbd{@key{ESC} @key{ESC}} instead." msgstr "" #. type: section #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:339 #, no-wrap msgid "Emacs Programming Tips" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:340 #, no-wrap msgid "programming conventions" msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:344 msgid "" "Following these conventions will make your program fit better into Emacs " "when it runs." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:350 msgid "" "Don't use @code{next-line} or @code{previous-line} in programs; nearly " "always, @code{forward-line} is more convenient as well as more predictable " "and robust. @xref{Text Lines}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:356 msgid "" "Don't call functions that set the mark, unless setting the mark is one of " "the intended features of your program. The mark is a user-level feature, so " "it is incorrect to change the mark except to supply a value for the user's " "benefit. @xref{The Mark}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:358 msgid "In particular, don't use any of these functions:" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:362 msgid "@code{beginning-of-buffer}, @code{end-of-buffer}" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:364 msgid "@code{replace-string}, @code{replace-regexp}" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:366 msgid "@code{insert-file}, @code{insert-buffer}" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:372 msgid "" "If you just want to move point, or replace a certain string, or insert a " "file or buffer's contents, without any of the other features intended for " "interactive users, you can replace these functions with one or two lines of " "simple Lisp code." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:377 msgid "" "Use lists rather than vectors, except when there is a particular reason to " "use a vector. Lisp has more facilities for manipulating lists than for " "vectors, and working with lists is usually more convenient." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:381 msgid "" "Vectors are advantageous for tables that are substantial in size and are " "accessed in random order (not searched front to back), provided there is no " "need to insert or delete elements (only lists allow that)." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:385 msgid "" "The recommended way to show a message in the echo area is with the " "@code{message} function, not @code{princ}. @xref{The Echo Area}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:390 msgid "" "When you encounter an error condition, call the function @code{error} (or " "@code{signal}). The function @code{error} does not return. @xref{Signaling " "Errors}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:393 msgid "" "Don't use @code{message}, @code{throw}, @code{sleep-for}, or @code{beep} to " "report errors." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:397 msgid "" "An error message should start with a capital letter but should not end with " "a period or other punctuation." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:403 msgid "" "It is occasionally useful to tell the user where an error originated, even " "if @code{debug-on-error} is @code{nil}. In such cases, a lower-case Lisp " "symbol can be prepended to the error message. For example, the error " "message ``Invalid input'' could be extended to say ``some-function: Invalid " "input''." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:408 msgid "" "A question asked in the minibuffer with @code{yes-or-no-p} or " "@code{y-or-n-p} should start with a capital letter and end with @samp{?}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:413 msgid "" "When you mention a default value in a minibuffer prompt, put it and the word " "@samp{default} inside parentheses. It should look like this:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:416 #, no-wrap msgid "Enter the answer (default 42):\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:425 msgid "" "In @code{interactive}, if you use a Lisp expression to produce a list of " "arguments, don't try to provide the correct default values for region or " "position arguments. Instead, provide @code{nil} for those arguments if they " "were not specified, and have the function body compute the default value " "when the argument is @code{nil}. For instance, write this:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:432 #, no-wrap msgid "" "(defun foo (pos)\n" " (interactive\n" " (list (if @var{specified} @var{specified-pos})))\n" " (unless pos (setq pos @var{default-pos}))\n" " ...)\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:436 msgid "rather than this:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:443 #, no-wrap msgid "" "(defun foo (pos)\n" " (interactive\n" " (list (if @var{specified} @var{specified-pos}\n" " @var{default-pos})))\n" " ...)\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:448 msgid "" "This is so that repetition of the command will recompute these defaults " "based on the current circumstances." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:453 msgid "" "You do not need to take such precautions when you use interactive specs " "@samp{d}, @samp{m} and @samp{r}, because they make special arrangements to " "recompute the argument values on repetition of the command." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:461 msgid "" "Many commands that take a long time to execute display a message that says " "something like @samp{Operating...} when they start, and change it to " "@samp{Operating...done} when they finish. Please keep the style of these " "messages uniform: @emph{no} space around the ellipsis, and @emph{no} period " "after @samp{done}. @xref{Progress}, for an easy way to generate such " "messages." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:467 msgid "" "Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e} " "command does: use a new local keymap that contains a command defined to " "switch back to the old local keymap. Or simply switch to another buffer and " "let the user switch back at will. @xref{Recursive Editing}." msgstr "" #. type: section #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:470 #, no-wrap msgid "Tips for Making Compiled Code Fast" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:471 #, no-wrap msgid "execution speed" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:472 #, no-wrap msgid "speedups" msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:476 msgid "" "Here are ways of improving the execution speed of byte-compiled Lisp " "programs." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:481 msgid "" "Profile your program, to find out where the time is being spent. " "@xref{Profiling}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:486 msgid "" "Use iteration rather than recursion whenever possible. Function calls are " "slow in Emacs Lisp even when a compiled function is calling another compiled " "function." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:492 msgid "" "Using the primitive list-searching functions @code{memq}, @code{member}, " "@code{assq}, or @code{assoc} is even faster than explicit iteration. It can " "be worth rearranging a data structure so that one of these primitive search " "functions can be used." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:500 msgid "" "Certain built-in functions are handled specially in byte-compiled code, " "avoiding the need for an ordinary function call. It is a good idea to use " "these functions rather than alternatives. To see whether a function is " "handled specially by the compiler, examine its @code{byte-compile} " "property. If the property is non-@code{nil}, then the function is handled " "specially." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:503 msgid "" "For example, the following input will show you that @code{aref} is compiled " "specially (@pxref{Array Functions}):" msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:508 #, no-wrap msgid "" "(get 'aref 'byte-compile)\n" " @result{} byte-compile-two-args\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:514 msgid "" "Note that in this case (and many others), you must first load the " "@file{bytecomp} library, which defines the @code{byte-compile} property." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:522 msgid "" "If calling a small function accounts for a substantial part of your " "program's running time, make the function inline. This eliminates the " "function call overhead. Since making a function inline reduces the " "flexibility of changing the program, don't do it unless it gives a " "noticeable speedup in something slow enough that users care about the " "speed. @xref{Inline Functions}." msgstr "" #. type: section #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:525 #, no-wrap msgid "Tips for Avoiding Compiler Warnings" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:526 #, no-wrap msgid "byte compiler warnings, how to avoid" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:532 msgid "" "Try to avoid compiler warnings about undefined free variables, by adding " "dummy @code{defvar} definitions for these variables, like this:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:535 #, no-wrap msgid "(defvar foo)\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:539 msgid "" "Such a definition has no effect except to tell the compiler not to warn " "about uses of the variable @code{foo} in this file." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:544 msgid "" "Similarly, to avoid a compiler warning about an undefined function that you " "know @emph{will} be defined, use a @code{declare-function} statement " "(@pxref{Declaring Functions})." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:549 msgid "" "If you use many functions, macros, and variables from a certain file, you " "can add a @code{require} (@pxref{Named Features, require}) for that package " "to avoid compilation warnings for them, like this:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:552 #, no-wrap msgid "(require 'foo)\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:557 msgid "" "If you need only macros from some file, you can require it only at compile " "time (@pxref{Eval During Compile}). For instance," msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:561 #, no-wrap msgid "" "(eval-when-compile\n" " (require 'foo))\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:571 msgid "" "If you bind a variable in one function, and use it or set it in another " "function, the compiler warns about the latter function unless the variable " "has a definition. But adding a definition would be unclean if the variable " "has a short name, since Lisp packages should not define short variable " "names. The right thing to do is to rename this variable to start with the " "name prefix used for the other functions and variables in your package." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:576 msgid "" "The last resort for avoiding a warning, when you want to do something that " "is usually a mistake but you know is not a mistake in your usage, is to put " "it inside @code{with-no-warnings}. @xref{Compiler Errors}." msgstr "" #. type: section #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:579 #, no-wrap msgid "Tips for Documentation Strings" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:580 #, no-wrap msgid "documentation strings, conventions and tips" msgstr "" #. type: findex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:582 #, no-wrap msgid "checkdoc-minor-mode" msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:586 msgid "" "Here are some tips and conventions for the writing of documentation " "strings. You can check many of these conventions by running the command " "@kbd{M-x checkdoc-minor-mode}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:591 msgid "" "Every command, function, or variable intended for users to know about should " "have a documentation string." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:596 msgid "" "An internal variable or subroutine of a Lisp program might as well have a " "documentation string. Documentation strings take up very little space in a " "running Emacs." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:602 msgid "" "Format the documentation string so that it fits in an Emacs window on an " "80-column screen. It is a good idea for most lines to be no wider than 60 " "characters. The first line should not be wider than 67 characters or it " "will look bad in the output of @code{apropos}." msgstr "" #. type: vindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:603 #, no-wrap msgid "emacs-lisp-docstring-fill-column" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:610 msgid "" "You can fill the text if that looks good. Emacs Lisp mode fills " "documentation strings to the width specified by " "@code{emacs-lisp-docstring-fill-column}. However, you can sometimes make a " "documentation string much more readable by adjusting its line breaks with " "care. Use blank lines between sections if the documentation string is long." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:617 msgid "" "The first line of the documentation string should consist of one or two " "complete sentences that stand on their own as a summary. @kbd{M-x apropos} " "displays just the first line, and if that line's contents don't stand on " "their own, the result looks bad. In particular, start the first line with a " "capital letter and end it with a period." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:621 msgid "" "For a function, the first line should briefly answer the question, ``What " "does this function do?'' For a variable, the first line should briefly " "answer the question, ``What does this value mean?''" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:625 msgid "" "Don't limit the documentation string to one line; use as many lines as you " "need to explain the details of how to use the function or variable. Please " "use complete sentences for the rest of the text too." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:631 msgid "" "When the user tries to use a disabled command, Emacs displays just the first " "paragraph of its documentation string---everything through the first blank " "line. If you wish, you can choose which information to include before the " "first blank line so as to make this display useful." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:639 msgid "" "The first line should mention all the important arguments of the function, " "and should mention them in the order that they are written in a function " "call. If the function has many arguments, then it is not feasible to " "mention them all in the first line; in that case, the first line should " "mention the first few arguments, including the most important arguments." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:646 msgid "" "When a function's documentation string mentions the value of an argument of " "the function, use the argument name in capital letters as if it were a name " "for that value. Thus, the documentation string of the function @code{eval} " "refers to its first argument as @samp{FORM}, because the actual argument " "name is @code{form}:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:649 #, no-wrap msgid "Evaluate FORM and return its value.\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:655 msgid "" "Also write metasyntactic variables in capital letters, such as when you show " "the decomposition of a list or vector into subunits, some of which may " "vary. @samp{KEY} and @samp{VALUE} in the following example illustrate this " "practice:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:659 #, no-wrap msgid "" "The argument TABLE should be an alist whose elements\n" "have the form (KEY . VALUE). Here, KEY is ...\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:665 msgid "" "Never change the case of a Lisp symbol when you mention it in a doc string. " "If the symbol's name is @code{foo}, write ``foo'', not ``Foo'' (which is a " "different symbol)." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:670 msgid "" "This might appear to contradict the policy of writing function argument " "values, but there is no real contradiction; the argument @emph{value} is not " "the same thing as the @emph{symbol} that the function uses to hold the " "value." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:674 msgid "" "If this puts a lower-case letter at the beginning of a sentence and that " "annoys you, rewrite the sentence so that the symbol is not at the start of " "it." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:677 msgid "Do not start or end a documentation string with whitespace." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:684 msgid "" "@strong{Do not} indent subsequent lines of a documentation string so that " "the text is lined up in the source code with the text of the first line. " "This looks nice in the source code, but looks bizarre when users view the " "documentation. Remember that the indentation before the starting " "double-quote is not part of the string!" msgstr "" #. type: anchor{#1} #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:686 msgid "Docstring hyperlinks" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:687 #, no-wrap msgid "curly quotes" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:688 #, no-wrap msgid "curved quotes" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:693 msgid "" "When a documentation string refers to a Lisp symbol, write it as it would be " "printed (which usually means in lower case), surrounding it with curved " "single quotes (@t{‘..’}). There are two exceptions: write @code{t} and " "@code{nil} without surrounding punctuation. For example:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:696 #, no-wrap msgid " CODE can be ‘lambda’, nil, or t.\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:701 msgid "" "@xref{Quotation Marks,,, emacs, The GNU Emacs Manual}, for how to enter " "curved single quotes." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:710 msgid "" "Documentation strings can also use an older single-quoting convention, which " "quotes symbols with grave accent @t{`} and apostrophe @t{'}: @t{`like-this'} " "rather than @t{‘like-this’}. This older convention was designed for " "now-obsolete displays in which grave accent and apostrophe were mirror " "images. Documentation using this convention is converted to the user's " "preferred format when it is copied into a help buffer. @xref{Keys in " "Documentation}." msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:711 #, no-wrap msgid "hyperlinks in documentation strings" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:721 msgid "" "Help mode automatically creates a hyperlink when a documentation string uses " "a single-quoted symbol name, if the symbol has either a function or a " "variable definition. You do not need to do anything special to make use of " "this feature. However, when a symbol has both a function definition and a " "variable definition, and you want to refer to just one of them, you can " "specify which one by writing one of the words @samp{variable}, " "@samp{option}, @samp{function}, or @samp{command}, immediately before the " "symbol name. (Case makes no difference in recognizing these indicator " "words.) For example, if you write" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:724 #, no-wrap msgid "This function sets the variable `buffer-file-name'.\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:729 msgid "" "then the hyperlink will refer only to the variable documentation of " "@code{buffer-file-name}, and not to its function documentation." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:734 msgid "" "If a symbol has a function definition and/or a variable definition, but " "those are irrelevant to the use of the symbol that you are documenting, you " "can write the words @samp{symbol} or @samp{program} before the symbol name " "to prevent making any hyperlink. For example," msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:739 #, no-wrap msgid "" "If the argument KIND-OF-RESULT is the symbol `list',\n" "this function returns a list of all the objects\n" "that satisfy the criterion.\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:744 msgid "" "does not make a hyperlink to the documentation, irrelevant here, of the " "function @code{list}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:749 msgid "" "Normally, no hyperlink is made for a variable without variable " "documentation. You can force a hyperlink for such variables by preceding " "them with one of the words @samp{variable} or @samp{option}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:754 msgid "" "Hyperlinks for faces are only made if the face name is preceded or followed " "by the word @samp{face}. In that case, only the face documentation will be " "shown, even if the symbol is also defined as a variable or as a function." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:759 msgid "" "To make a hyperlink to Info documentation, write the single-quoted name of " "the Info node (or anchor), preceded by @samp{info node}, @samp{Info node}, " "@samp{info anchor} or @samp{Info anchor}. The Info file name defaults to " "@samp{emacs}. For example," msgstr "" #. type: smallexample #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:762 #, no-wrap msgid "See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:767 msgid "" "To make a hyperlink to a man page, write the single-quoted name of the man " "page, preceded by @samp{Man page}, @samp{man page}, or @samp{man page for}. " "For example," msgstr "" #. type: smallexample #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:770 #, no-wrap msgid "See the man page `chmod(1)' for details.\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:777 msgid "" "The Info documentation is always preferable to man pages, so be sure to link " "to an Info manual where available. For example, @command{chmod} is " "documented in the GNU Coreutils manual, so it is better to link to that " "instead of the man page." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:781 msgid "" "To link to a customization group, write the single-quoted name of the group, " "preceded by @samp{customization group} (the first character in each word is " "case-insensitive). For example," msgstr "" #. type: smallexample #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:784 #, no-wrap msgid "See the customization group `whitespace' for details.\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:788 msgid "" "Finally, to create a hyperlink to URLs, write the single-quoted URL, " "preceded by @samp{URL}. For example," msgstr "" #. type: smallexample #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:792 #, no-wrap msgid "" "The GNU project wesite has more information (see URL\n" "`https://www.gnu.org/').\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:802 msgid "" "Don't write key sequences directly in documentation strings. Instead, use " "the @samp{\\\\[@dots{}]} construct to stand for them. For example, instead " "of writing @samp{C-f}, write the construct @samp{\\\\[forward-char]}. When " "Emacs displays the documentation string, it substitutes whatever key is " "currently bound to @code{forward-char}. (This is normally @samp{C-f}, but " "it may be some other character if the user has moved key bindings.) " "@xref{Keys in Documentation}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:811 msgid "" "In documentation strings for a major mode, you will want to refer to the key " "bindings of that mode's local map, rather than global ones. Therefore, use " "the construct @samp{\\\\<@dots{}>} once in the documentation string to " "specify which key map to use. Do this before the first use of " "@samp{\\\\[@dots{}]}. The text inside the @samp{\\\\<@dots{}>} should be " "the name of the variable containing the local keymap for the major mode." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:818 msgid "" "Each use of @samp{\\\\[@dots{}]} slows the display of the documentation " "string by a tiny amount. If you use a lot of them, these tiny slowdowns " "will add up, and might become tangible, especially on slow systems. So our " "recommendation is not to over-use them; e.g., try to avoid using more than " "one reference to the same command in the same doc string." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:826 msgid "" "For consistency, phrase the verb in the first sentence of a function's " "documentation string as an imperative---for instance, use ``Return the cons " "of A and B.@:'' in preference to ``Returns the cons of A and B@.'' Usually " "it looks good to do likewise for the rest of the first paragraph. " "Subsequent paragraphs usually look better if each sentence is indicative and " "has a proper subject." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:833 msgid "" "The documentation string for a function that is a yes-or-no predicate should " "start with words such as ``Return t if'', to indicate explicitly what " "constitutes truth. The word ``return'' avoids starting the sentence with " "lower-case ``t'', which could be somewhat distracting." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:839 msgid "" "Write documentation strings in the active voice, not the passive, and in the " "present tense, not the future. For instance, use ``Return a list containing " "A and B.@:'' instead of ``A list containing A and B will be returned.''" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:844 msgid "" "Avoid using the word ``cause'' (or its equivalents) unnecessarily. Instead " "of, ``Cause Emacs to display text in boldface'', write just ``Display text " "in boldface''." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:850 msgid "" "Avoid using ``iff'' (a mathematics term meaning ``if and only if''), since " "many people are unfamiliar with it and mistake it for a typo. In most " "cases, the meaning is clear with just ``if''. Otherwise, try to find an " "alternate phrasing that conveys the meaning." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:858 msgid "" "Try to avoid using abbreviations such as ``e.g.'' (for ``for example''), " "``i.e.'' (for ``that is''), ``no.'' (for ``number''), ``c.f.'' (for ``in " "contrast to'') and ``w.r.t.'' (for ``with respect to'') as much as " "possible. It is almost always clearer and easier to read the expanded " "version.@footnote{We do use these occasionally, but try not to overdo it.}" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:863 msgid "" "When a command is meaningful only in a certain mode or situation, do mention " "that in the documentation string. For example, the documentation of " "@code{dired-find-file} is:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:866 #, no-wrap msgid "In Dired, visit the file or directory named on this line.\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:871 msgid "" "When you define a variable that represents an option users might want to " "set, use @code{defcustom}. @xref{Defining Variables}." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:877 msgid "" "The documentation string for a variable that is a yes-or-no flag should " "start with words such as ``Non-nil means'', to make it clear that all " "non-@code{nil} values are equivalent and indicate explicitly what @code{nil} " "and non-@code{nil} mean." msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:881 msgid "" "If a line in a documentation string begins with an open-parenthesis, " "consider writing a backslash before the open-parenthesis, like this:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:885 #, no-wrap msgid "" "The argument FOO can be either a number\n" "\\(a buffer position) or a string (a file name).\n" msgstr "" #. type: itemize #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:892 msgid "" "This avoids a bug in Emacs versions older than 27.1, where the @samp{(} was " "treated as the start of a defun (@pxref{Defuns,, Defuns, emacs, The GNU " "Emacs Manual}). If you do not anticipate anyone editing your code with " "older Emacs versions, there is no need for this work-around." msgstr "" #. type: section #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:895 #, no-wrap msgid "Tips on Writing Comments" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:896 #, no-wrap msgid "comments, Lisp convention for" msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:899 msgid "We recommend these conventions for comments:" msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:901 #, no-wrap msgid ";" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:906 msgid "" "Comments that start with a single semicolon, @samp{;}, should all be aligned " "to the same column on the right of the source code. Such comments usually " "explain how the code on that line does its job. For example:" msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:913 #, no-wrap msgid "" "(setq base-version-list ; There was a base\n" " (assoc (substring fn 0 start-vn) ; version to which\n" " file-version-assoc-list)) ; this looks like\n" " ; a subversion.\n" msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:916 #, no-wrap msgid ";;" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:921 msgid "" "Comments that start with two semicolons, @samp{;;}, should be aligned to the " "same level of indentation as the code. Such comments usually describe the " "purpose of the following lines or the state of the program at that point. " "For example:" msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:929 #, no-wrap msgid "" "(prog1 (setq auto-fill-function\n" " @dots{}\n" " @dots{}\n" " ;; Update mode line.\n" " (force-mode-line-update)))\n" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:933 msgid "We also normally use two semicolons for comments outside functions." msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:938 #, no-wrap msgid "" ";; This Lisp code is run in Emacs when it is to operate as\n" ";; a server for other processes.\n" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:947 msgid "" "If a function has no documentation string, it should instead have a " "two-semicolon comment right before the function, explaining what the " "function does and how to call it properly. Explain precisely what each " "argument means and how the function interprets its possible values. It is " "much better to convert such comments to documentation strings, though." msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:948 #, no-wrap msgid ";;;" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:956 msgid "" "Comments that start with three (or more) semicolons, @samp{;;;}, should " "start at the left margin. We use them for comments that should be " "considered a heading by Outline minor mode. By default, comments starting " "with at least three semicolons (followed by a single space and a " "non-whitespace character) are considered section headings, comments starting " "with two or fewer are not." msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:961 msgid "" "(Historically, triple-semicolon comments have also been used for commenting " "out lines within a function, but this use is discouraged in favor of using " "just two semicolons. This also applies when commenting out entire " "functions; when doing that use two semicolons as well.)" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:964 msgid "" "Three semicolons are used for top-level sections, four for sub-sections, " "five for sub-sub-sections and so on." msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:967 msgid "" "Typically libraries have at least four top-level sections. For example when " "the bodies of all of these sections are hidden:" msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:974 #, no-wrap msgid "" ";;; backquote.el --- implement the ` Lisp construct...\n" ";;; Commentary:...\n" ";;; Code:...\n" ";;; backquote.el ends here\n" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:980 msgid "" "(In a sense the last line is not a section heading as it must never be " "followed by any text; after all it marks the end of the file.)" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:986 msgid "" "For longer libraries it is advisable to split the code into multiple " "sections. This can be done by splitting the @samp{Code:} section into " "multiple sub-sections. Even though that was the only recommended approach " "for a long time, many people have chosen to use multiple top-level code " "sections instead. You may chose either style." msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:993 msgid "" "Using multiple top-level code sections has the advantage that it avoids " "introducing an additional nesting level but it also means that the section " "named @samp{Code} does not contain all the code, which is awkward. To avoid " "that, you should put no code at all inside that section; that way it can be " "considered a separator instead of a section heading." msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:998 msgid "" "Finally, we recommend that you don't end headings with a colon or any other " "punctuation for that matter. For historic reasons the @samp{Code:} and " "@samp{Commentary:} headings end with a colon, but we recommend that you " "don't do the same for other headings anyway." msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1007 msgid "" "Generally speaking, the @kbd{M-;} (@code{comment-dwim}) command " "automatically starts a comment of the appropriate type; or indents an " "existing comment to the right place, depending on the number of semicolons. " "@xref{Comments,, Manipulating Comments, emacs, The GNU Emacs Manual}." msgstr "" #. type: section #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1009 #, no-wrap msgid "Conventional Headers for Emacs Libraries" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1010 #, no-wrap msgid "header comments" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1011 #, no-wrap msgid "library header comments" msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1018 msgid "" "Emacs has conventions for using special comments in Lisp libraries to divide " "them into sections and give information such as who wrote them. Using a " "standard format for these items makes it easier for tools (and people) to " "extract the relevant information. This section explains these conventions, " "starting with an example:" msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1022 #, no-wrap msgid "" ";;; foo.el --- Support for the Foo programming language -*- " "lexical-binding: t; -*-\n" "\n" msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1024 #, no-wrap msgid ";; Copyright (C) 2010-2021 Your Name\n" msgstr "" #. type: smallexample #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1029 #, no-wrap msgid "" ";; Author: Your Name <yourname@@example.com>\n" ";; Maintainer: Someone Else <someone@@example.com>\n" ";; Created: 14 Jul 2010\n" msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1032 #, no-wrap msgid "" ";; Keywords: languages\n" ";; URL: https://example.com/foo\n" "\n" msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1034 #, no-wrap msgid "" ";; This file is not part of GNU Emacs.\n" "\n" msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1038 #, no-wrap msgid "" ";; This file is free software@dots{}\n" "@dots{}\n" ";; along with this file. If not, see <https://www.gnu.org/licenses/>.\n" msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1042 msgid "The very first line should have this format:" msgstr "" #. type: example #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1045 #, no-wrap msgid ";;; @var{filename} --- @var{description} -*- lexical-binding: t; -*-\n" msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1052 msgid "" "The description should be contained in one line. If the file needs to set " "more variables in the @samp{-*-} specification, add it after " "@code{lexical-binding}. If this would make the first line too long, use a " "Local Variables section at the end of the file." msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1061 msgid "" "The copyright notice usually lists your name (if you wrote the file). If " "you have an employer who claims copyright on your work, you might need to " "list them instead. Do not say that the copyright holder is the Free " "Software Foundation (or that the file is part of GNU Emacs) unless your file " "has been accepted into the Emacs distribution. For more information on the " "form of copyright and license notices, see " "@uref{https://www.gnu.org/licenses/gpl-howto.html, the guide on the GNU " "website}." msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1065 msgid "" "After the copyright notice come several @dfn{header comment} lines, each " "beginning with @samp{;; @var{header-name}:}. Here is a table of the " "conventional possibilities for @var{header-name}:" msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1067 #, no-wrap msgid "Author" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1073 msgid "" "This header states the name and email address of at least the principal " "author of the library. If there are multiple authors, list them on " "continuation lines led by @code{;;} and a tab or at least two spaces. We " "recommend including a contact email address, of the form @samp{<@dots{}>}. " "For example:" msgstr "" #. type: group #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1079 #, no-wrap msgid "" ";; Author: Your Name <yourname@@example.com>\n" ";; Someone Else <someone@@example.com>\n" ";; Another Person <another@@example.com>\n" msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1082 #, no-wrap msgid "Maintainer" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1086 msgid "" "This header has the same format as the Author header. It lists the " "person(s) who currently maintain(s) the file (respond to bug reports, etc.)." msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1092 msgid "" "If there is no Maintainer header, the person(s) in the Author header is/are " "presumed to be the maintainer(s). Some files in Emacs use " "@samp{emacs-devel@@gnu.org} for the maintainer, which means the author is no " "longer responsible for the file, and that it is maintained as part of Emacs." msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1093 #, no-wrap msgid "Created" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1096 msgid "" "This optional line gives the original creation date of the file, and is for " "historical interest only." msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1097 #, no-wrap msgid "Version" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1104 msgid "" "If you wish to record version numbers for the individual Lisp program, put " "them in this line. Lisp files distributed with Emacs generally do not have " "a @samp{Version} header, since the version number of Emacs itself serves the " "same purpose. If you are distributing a collection of multiple files, we " "recommend not writing the version in every file, but only the main one." msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1105 #, no-wrap msgid "Keywords" msgstr "" #. type: vindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1106 #, no-wrap msgid "checkdoc-package-keywords-flag" msgstr "" #. type: findex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1107 #, no-wrap msgid "checkdoc-package-keywords" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1114 msgid "" "This line lists keywords for the @code{finder-by-keyword} help command. " "Please use that command to see a list of the meaningful keywords. The " "command @kbd{M-x checkdoc-package-keywords @key{RET}} will find and display " "any keywords that are not in @code{finder-known-keywords}. If you set the " "variable @code{checkdoc-package-keywords-flag} non-@code{nil}, checkdoc " "commands will include the keyword verification in its checks." msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1118 msgid "" "This field is how people will find your package when they're looking for " "things by topic. To separate the keywords, you can use spaces, commas, or " "both." msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1122 msgid "" "The name of this field is unfortunate, since people often assume it is the " "place to write arbitrary keywords that describe their package, rather than " "just the relevant Finder keywords." msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1123 #, no-wrap msgid "URL" msgstr "" #. type: itemx #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1124 #, no-wrap msgid "Homepage" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1126 msgid "These lines state the website of the library." msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1127 #, no-wrap msgid "Package-Version" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1132 msgid "" "If @samp{Version} is not suitable for use by the package manager, then a " "package can define @samp{Package-Version}; it will be used instead. This is " "handy if @samp{Version} is an RCS id or something else that cannot be parsed " "by @code{version-to-list}. @xref{Packaging Basics}." msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1133 #, no-wrap msgid "Package-Requires" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1139 msgid "" "If this exists, it names packages on which the current package depends for " "proper operation. @xref{Packaging Basics}. This is used by the package " "manager both at download time (to ensure that a complete set of packages is " "downloaded) and at activation time (to ensure that a package is only " "activated if all its dependencies have been)." msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1146 msgid "" "Its format is a list of lists on a single line. The @code{car} of each " "sub-list is the name of a package, as a symbol. The @code{cadr} of each " "sub-list is the minimum acceptable version number, as a string that can be " "parsed by @code{version-to-list}. An entry that lacks a version (i.e., an " "entry which is just a symbol, or a sub-list of one element) is equivalent to " "entry with version \"0\". For instance:" msgstr "" #. type: smallexample #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1149 #, no-wrap msgid ";; Package-Requires: ((gnus \"1.0\") (bubbles \"2.7.2\") cl-lib (seq))\n" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1154 msgid "" "The package code automatically defines a package named @samp{emacs} with the " "version number of the currently running Emacs. This can be used to require " "a minimal version of Emacs for a package." msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1160 msgid "" "Just about every Lisp library ought to have the @samp{Author} and " "@samp{Keywords} header comment lines. Use the others if they are " "appropriate. You can also put in header lines with other header " "names---they have no standard meanings, so they can't do any harm." msgstr "" #. type: Plain text #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1164 msgid "" "We use additional stylized comments to subdivide the contents of the library " "file. These should be separated from anything else by blank lines. Here is " "a table of them:" msgstr "" #. type: cindex #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1165 #, no-wrap msgid "commentary, in a Lisp library" msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1167 #, no-wrap msgid ";;; Commentary:" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1173 msgid "" "This begins introductory comments that explain how the library works. It " "should come right after the copying permissions, terminated by a " "@samp{Change Log}, @samp{History} or @samp{Code} comment line. This text is " "used by the Finder package, so it should make sense in that context." msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1174 #, no-wrap msgid ";;; Change Log:" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1180 msgid "" "This begins an optional log of changes to the file over time. Don't put too " "much information in this section---it is better to keep the detailed logs in " "a version control system (as Emacs does) or in a separate @file{ChangeLog} " "file. @samp{History} is an alternative to @samp{Change Log}." msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1181 #, no-wrap msgid ";;; Code:" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1183 msgid "This begins the actual code of the program." msgstr "" #. type: item #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1184 #, no-wrap msgid ";;; @var{filename} ends here" msgstr "" #. type: table #: /Users/suzume/Documents/Repositories/Projet OmegaT de Documentation Emacs - #: Sources/doc/lispref/tips.texi:1188 msgid "" "This is the @dfn{footer line}; it appears at the very end of the file. Its " "purpose is to enable people to detect truncated versions of the file from " "the lack of a footer line." msgstr ""