sunoc/documentation_emacs_test
1
0
Fork 0
forked from brandelune/documentation_emacs
Code Pull Requests Activity
690768264d
documentation_emacs_test/source/lispref/tips.texi.fr.po
Lilian 92ad556866 Commit source files
2022-03-08 11:11:57 +01:00

2413 lines
87 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 ""
View Git Blame Copy Permalink