From 32ea69d5de7ccba3955cafe29ae44218a792b7b7 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Thu, 18 Sep 2025 05:23:24 -0600 Subject: [PATCH] INSTALL: Better describe pod markup; mention perldoc This gives more complete advice to someone reading this document about how to read it. --- INSTALL | 43 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/INSTALL b/INSTALL index 7228b5d5b7..3e95bc0946 100644 --- a/INSTALL +++ b/INSTALL @@ -55,17 +55,46 @@ For information on what's new in this release, see the F file. For more information about how to find more specific detail about changes, see the Changes file. -=head1 DESCRIPTION +=begin comment + +=head1 FORMAT OF THIS DOCUMENT This document is written in pod format as an easy way to indicate its -structure. The pod format is described in F, but you can -read it as is with any pager or editor. Headings and items are marked -by lines beginning with '='. The other mark-up used is +structure. On many systems, you can just type - B embolden text, used for switches, programs or commands - C literal code - L A link (cross reference) to name + perldoc INSTALL + +and get a nicely formatted version. But if not, you can read it as is with any +pager or editor. If you are doing that, here are a few hints. Lines that have +an "=" in column 1 are commands to perldoc. You've already seen lines like + + =head1 NAME + +This makes a top level heading containing the word "NAME". "=head2" would make +a secondary-level heading, and so forth. Other commands are + + =over increase indentation + =back decrease indentation + =item introduces an item in a list + =for ignore these lines; they are directives to help various + tools, such as creating documentation cross referencing + =begin comment ignore this line + =end comment ignore this line + +The styling of text is changed by these in-line mark-up commands + + B embolden "text", used for switches, programs or commands + C literal code + L A link (cross reference) to name; you may have to squint + hard to make out the name from other stuff F A filename + S "text" is output all on the same line + +More detail on pod format is given in F. + +=end comment + +=head1 DESCRIPTION Although most of the defaults are probably fine for most users, you should probably at least skim through this document before