From 6f360c5aad7558e0404454783b9dd902e46c034e Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Tue, 21 Sep 2021 18:12:07 +0200 Subject: [PATCH] ; Stylistic docfixes in htmlfontify.el found by checkdoc --- lisp/htmlfontify.el | 232 ++++++++++++++++++++++++++++---------------- 1 file changed, 146 insertions(+), 86 deletions(-) diff --git a/lisp/htmlfontify.el b/lisp/htmlfontify.el index e63910d857d..9fe6e825f78 100644 --- a/lisp/htmlfontify.el +++ b/lisp/htmlfontify.el @@ -90,23 +90,30 @@ "The generator meta tag for this version of htmlfontify.") (defconst htmlfontify-manual "Htmlfontify Manual" - "Copy and convert buffers and files to HTML, adding hyperlinks between files -\(driven by etags) if requested. -\nInteractive functions: + "Copy and convert buffers and files to HTML. +Add hyperlinks between files driven by etags) if requested. + +Interactive functions: `htmlfontify-buffer' `htmlfontify-run-etags' `htmlfontify-copy-and-link-dir' `htmlfontify-load-rgb-file' - `htmlfontify-unload-rgb-file'\n -In order to:\n + `htmlfontify-unload-rgb-file' + +In order to: + fontify a file you have open: \\[htmlfontify-buffer] prepare the etags map for a directory: \\[htmlfontify-run-etags] -copy a directory, fontifying as you go: \\[htmlfontify-copy-and-link-dir]\n +copy a directory, fontifying as you go: \\[htmlfontify-copy-and-link-dir] + The following might be useful when running non-windowed or in batch mode: -\(note that they shouldn't be necessary - we have a built in map)\n +\(note that they shouldn't be necessary - we have a built in map) + load an X11 style rgb.txt file: \\[htmlfontify-load-rgb-file] -unload the current rgb.txt file: \\[htmlfontify-unload-rgb-file]\n -And here's a programmatic example:\n +unload the current rgb.txt file: \\[htmlfontify-unload-rgb-file] + +And here's a programmatic example: + \(defun rtfm-build-page-header (file style) (format \"#define TEMPLATE red+black.html #define DEBUG 1 @@ -148,7 +155,8 @@ This is called with two arguments (the filename relative to the top level source directory being etag'd and fontified), and a string containing the text to embed in the document. It should return a string that will be used as the header for the -htmlfontified version of the source file.\n +htmlfontified version of the source file. + See also `hfy-page-footer'." ;; FIXME: Why place such a :tag everywhere? Isn't it imposing your ;; own Custom preference on your users? --Stef @@ -233,8 +241,10 @@ These functions will be called with the HTML buffer as the current buffer." "Fallback `defface' specification for the face `default', used when `hfy-display-class' has been set (the normal htmlfontify way of extracting potentially non-current face information doesn't necessarily work for -`default').\n -Example: I customize this to:\n +`default'). + +Example: I customize this to: + \((t :background \"black\" :foreground \"white\" :family \"misc-fixed\"))" :tag "default-face-definition" :type '(alist)) @@ -244,8 +254,9 @@ Example: I customize this to:\n "\x01" "\\([0-9]+\\)" "," "\\([0-9]+\\)$" "\\|" ".*\x7f[0-9]+,[0-9]+$") - "Regex used to parse an etags entry: must have 3 subexps, corresponding, -in order, to:\n + "Regex used to parse an etags entry. +This must have 3 subexps, corresponding, in order, to: + 1 - The tag 2 - The line 3 - The char (point) at which the tag occurs." @@ -302,7 +313,8 @@ done;") :type '(alist :key-type (string) :value-type (string))) (defcustom hfy-etags-bin "etags" - "Location of etags binary (we begin by assuming it's in your path).\n + "Location of etags binary (we begin by assuming it's in your path). + Note that if etags is not in your path, you will need to alter the shell commands in `hfy-etags-cmd-alist'." :tag "etags-bin" @@ -346,7 +358,8 @@ commands in `hfy-etags-cmd-alist'." (cdr (assoc (hfy-which-etags) hfy-etags-cmd-alist)) "The etags equivalent command to run in a source directory to generate a tags file for the whole source tree from there on down. The command should emit -the etags output on stdout.\n +the etags output on stdout. + Two canned commands are provided - they drive Emacs's etags and exuberant-ctags' etags respectively." :tag "etags-command" @@ -356,9 +369,10 @@ exuberant-ctags' etags respectively." (cons 'choice clist))) (defcustom hfy-istext-command "file %s | sed -e 's@^[^:]*:[ \t]*@@'" - "Command to run with the name of a file, to see whether it is a text file -or not. The command should emit a string containing the word `text' if -the file is a text file, and a string not containing `text' otherwise." + "Command to run with the name of a file, to see if it is a text file or not. +The command should emit a string containing the word `text' if +the file is a text file, and a string not containing `text' +otherwise." :tag "istext-command" :type '(string)) @@ -372,8 +386,10 @@ the file is a text file, and a string not containing `text' otherwise." "Display class to use to determine which display class to use when calculating a face's attributes. This is useful when, for example, you are running Emacs on a tty or in batch mode, and want htmlfontify to have -access to the face spec you would use if you were connected to an X display.\n -Some valid class specification elements are:\n +access to the face spec you would use if you were connected to an X display. + +Some valid class specification elements are: + (class color) (class grayscale) (background dark) @@ -383,14 +399,17 @@ Some valid class specification elements are:\n (type motif) (type lucid) Multiple values for a tag may be combined, to indicate that any one or more -of these values in the specification key constitutes a match, eg:\n -\((class color grayscale) (type tty)) would match any of:\n +of these values in the specification key constitutes a match, eg: + +\((class color grayscale) (type tty)) would match any of: + ((class color)) ((class grayscale)) ((class color grayscale)) ((class color foo)) ((type tty)) - ((type tty) (class color))\n + ((type tty) (class color)) + and so on." :type '(alist :key-type (symbol) :value-type (symbol)) :tag "display-class" @@ -407,7 +426,9 @@ and so on." (define-obsolete-variable-alias 'hfy-optimisations 'hfy-optimizations "25.1") (defcustom hfy-optimizations (list 'keep-overlays) - "Optimizations to turn on: So far, the following have been implemented:\n + "Optimizations to turn on. +So far, the following have been implemented: + merge-adjacent-tags: If two (or more) span tags are adjacent, identical and separated by nothing more than whitespace, they will be merged into one span. @@ -417,16 +438,19 @@ and so on." output. keep-overlays : More of a bell (or possibly whistle) than an optimization - If on, preserve overlay highlighting - (cf ediff or goo-font-lock) as well as basic faces.\n + (cf ediff or goo-font-lock) as well as basic faces. + body-text-only : Emit only body-text. In concrete terms, 1. Suppress calls to `hfy-page-header' and `hfy-page-footer' 2. Pretend that `div-wrapper' option above is turned off 3. Don't enclose output in
tags - And the following are planned but not yet available:\n + And the following are planned but not yet available: + kill-context-leak : Suppress hyperlinking between files highlighted by - different modes.\n + different modes. + Note: like compiler optimizations, these optimize the _output_ of the code, not the processing of the source itself, and are therefore likely to slow htmlfontify down, at least a little. Except for skip-refontification, @@ -442,20 +466,28 @@ which can never slow you down, but may result in incomplete fontification." :tag "optimizations") (defvar hfy-tags-cache nil - "Alist of the form:\n -\((\"/src/dir/0\" . tag-hash0) (\"/src/dir/1\" tag-hash1) ...)\n -Each tag hash entry then contains entries of the form:\n -\"tag_string\" => ((\"file/name.ext\" line char) ... )\n -ie an alist mapping (relative) file paths to line and character offsets.\n + "Alist of the form: + +\((\"/src/dir/0\" . tag-hash0) (\"/src/dir/1\" tag-hash1) ...) + +Each tag hash entry then contains entries of the form: + +\"tag_string\" => ((\"file/name.ext\" line char) ... ) + +ie an alist mapping (relative) file paths to line and character offsets. + See also `hfy-load-tags-cache'.") (defvar hfy-tags-sortl nil - "Alist of the form ((\"/src/dir\" . (tag0 tag1 tag2)) ... )\n -where the tags are stored in descending order of length.\n + "Alist of the form ((\"/src/dir\" . (tag0 tag1 tag2)) ... ) + +where the tags are stored in descending order of length. + See also `hfy-load-tags-cache'.") (defvar hfy-tags-rmap nil - "Alist of the form ((\"/src/dir\" . tag-rmap-hash))\n + "Alist of the form ((\"/src/dir\" . tag-rmap-hash)) + where tag-rmap-hash has entries of the form: \"tag_string\" => ( \"file/name.ext\" line char ) Unlike `hfy-tags-cache' these are the locations of occurrences of @@ -467,8 +499,10 @@ Properties may be repeated, in which case later properties should be treated as if they were inherited from a `parent' font. \(For some properties, only the first encountered value is of any importance, for others the values might be cumulative, and for others they might be -cumulative in a complex way.)\n -Some examples:\n +cumulative in a complex way.) + +Some examples: + \(hfy-face-to-style \\='default) => ((\"background\" . \"rgb(0, 0, 0)\") (\"color\" . \"rgb(255, 255, 255)\") @@ -477,27 +511,31 @@ Some examples:\n (\"font-stretch\" . \"normal\") (\"font-family\" . \"misc-fixed\") (\"font-size\" . \"13pt\") - (\"text-decoration\" . \"none\"))\n + (\"text-decoration\" . \"none\")) + \(hfy-face-to-style \\='Info-title-3-face) => ((\"font-weight\" . \"700\") (\"font-family\" . \"helv\") (\"font-size\" . \"120%\") - (\"text-decoration\" . \"none\"))\n") + (\"text-decoration\" . \"none\"))") (defvar hfy-sheet-assoc 'please-ignore-this-line - "An assoc with elements of the form (face-name style-name . style-string):\n + "An assoc with elements of the form (face-name style-name . style-string): + \((default \"default\" . \"{background: black; color: white}\") (font-lock-string-face \"string\" . \"{color: rgb(64,224,208)}\"))" ) (defvar hfy-facemap-assoc 'please-ignore-this-line "An assoc of (point . FACE-SYMBOL) or (point . DEFFACE-LIST) and (point . \\='end) elements, in descending order of point value -\(ie from the file's end to its beginning).\n +\(ie from the file's end to its beginning). + The map is in reverse order because inserting a