"Manual? What's that?"


perl-mode is a thing. So is cperl-mode , a more extensive major mode for editing Perl. I’ve tried out the latter briefly for viewing a script, then did succumb to my curiosity and checked the sources after noticing weird behaviour.

;; DO NOT FORGET to read micro-docs (available from `Perl' menu) <<<<<<;; or as help on variables `cperl-tips', `cperl-problems', <<<<<<;; `cperl-praise', `cperl-speed'. <<<<<<


(defvar cperl-problems 'please-ignore-this-line "Description of problems in CPerl mode.Some faces will not be shown on some versions of Emacs unless youinstall choose-color.el, available from http://ilyaz.org/software/emacs`fill-paragraph' on a comment may leave the point behind theparagraph. It also triggers a bug in some versions of Emacs (CPerl triesto detect it and bulk out).See documentation of a variable `cperl-problems-old-emaxen' for theproblems which disappear if you upgrade Emacs to a reasonably newversion (20.3 for Emacs, and those of 2004 for XEmacs).")

Notice the name of this variable, its docstring (which doesn’t describe it) and the peculiar please-ignore-this-line value. Why would you possibly abuse it for what looks like something for a manual?

(condition-case nil (progn (require 'easymenu) (easy-menu-define cperl-menu cperl-mode-map "Menu for CPerl mode" '("Perl" […] ("Micro-docs" ["Tips" (describe-variable 'cperl-tips) t] ["Problems" (describe-variable 'cperl-problems) t] ["Speed" (describe-variable 'cperl-speed) t] ["Praise" (describe-variable 'cperl-praise) t] ["Faces" (describe-variable 'cperl-tips-faces) t] ["CPerl mode" (describe-function 'cperl-mode) t] ["CPerl version" (message "The version of master-file for this CPerl is %s-Emacs" cperl-version) t]))))(error nil))

So, that’s why. Clicking on these menu itemsgives you a poor substitute for a properly written manual.