structural improvements to the texinfo manual

Signed-off-by: Mattias Andrée <maandree@member.fsf.org>

1 files changed, 85 insertions, 324 deletions

diff --git a/doc/info/scrotty.texinfo b/doc/info/scrotty.texinfo
index c26100e..7fa7477 100644
--- a/doc/info/scrotty.texinfo
+++ b/doc/info/scrotty.texinfo
@@ -1,342 +1,103 @@
 \input texinfo   @c -*-texinfo-*-
-
 @c %**start of header
-@setfilename scrotty.info
-@settitle scrotty
-@afourpaper
 @documentencoding UTF-8
-@documentlanguage en
-@finalout
-@c %**end of header
-
-
-@dircategory Multimedia
-@direntry
-* scrotty: (scrotty).                Take a screenshot of the framebuffer
-@end direntry
-
-
+@include reusable/macros.texinfo
 @copying
-Copyright @copyright{} 2014, 2015 Mattias Andrée
+@c --------------------------------------------------------------------------------
+Copyright @copyright{} 2014, 2015  @w{Mattias Andrée @e{maandree@@member.fsf.org}}
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
+under the terms of the GNU Free Documentation License, Version@tie{}1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``Free Software Needs Free Documentation'', the
+``GNU General Public License'', the ``GNU Free Documentation License'',
+with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the
+license is included in the section entitled ``GNU Free Documentation License''.
 @end quotation
+@c THIS WAS LAST CHANGED 2015-DECEMBER-08 UTC
+@c When updated, please remember to update hardcopy-copying.texinfo too.
+@c --------------------------------------------------------------------------------
 @end copying
 
-@ifnottex
-@node Top
-@top scrotty -- Take a screenshot of the framebuffer
-@insertcopying
-@end ifnottex
-
-@titlepage
-@title scrotty
-@subtitle Take a screenshot of the framebuffer
-@author by Mattias Andrée (maandree)
-
-@page
-@center `I don't know how to make a screenshot, because I normally use my computer in
-@center text-mode. I have @sc{X} and @sc{GNOME} installed, but I use them only occasionally.' --- rms
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@contents
-
-
-
-@menu
-* Overview::                        Brief overview of @command{scrotty}.
-* Invoking::                        Invocation of @command{scrotty}.
-* strftime::                        Syntax support via @code{strftime}.
-* GNU Free Documentation License::  Copying and sharing this manual.
-@end menu
-
-
-
-@node Overview
-@chapter Overview
-
-@command{scrotty} is a simple command for taking a screenshot
-of your framebuffers. It can be used to take a screenshot of
-your @sc{TTY} session, but it cannot take a screenshot of your
-@sc{X} session.@footnote{Unless it is for some reason is
-rendered on the framebuffer.}
-
-@command{scrotty} is designed after @command{scrot}, but
-includes a some improvements. Namely it does not support
-delaying the screenshot, selecting image quality or creating
-thumbnails, but it has support for adding arbitrary arguments
-to @command{convert} (from the ImageMagick project), which
-is used to save the image.
-
-@command{scrotty} reads the data stored in the framebuffers,
-convert it the @sc{PNM} images and pipes it to @command{convert}
-to create @sc{PNG} images.
-
-
-
-@node Invoking
-@chapter Invoking
-
-@command{scrotty} recognises four options:
-
-@table @option
-@item --help
-Print usage information and exit.
-@item --version
-Print program name and version and exit.
-@item --copyright
-Print copyright information and exit.
-@item --raw
-Save the images in portable anymap format
-(PNM), rather than in Portable Network
-Graphics (PNG). If this option is used,
-and no arguments for @command{convert}
-is specified, @command{convert} will not
-be used, and there will be not requirement
-to have ImageMagick installed.
-
-PNM images are highly compressable with
-@command{bzip2}. Compressed images are comparable
-in size with @sc{PNG},@footnote{Usually a few
-bytes in difference.} and can in fact be smaller.
-@item --exec CMD
-Run a command for each saved image.
-@end table
-
-In addition to these options, a filename
-pattern, that does not start with a dash,
-can be added. This filename pattern selects
-with what filename the image should be saved.
-
-Further, it is possible add @option{--}
-followed by additional options to add when
-@command{scrotty} spawns @command{convert}.
-
-Both the @option{--exec} and filename pattern
-parameters can take format specifiers that are
-expanded by @command{scrotty} when encountered.
-There are two types of format specifier.
-Characters preceded by a `%' are interpreted
-by @code{strftime}. See @ref{strftime} or the
-manual for your implemenation of @command{strftime}
-for examples. These options may be used to refer
-to the current date and time. The second kind are
-internal to scrotty and are prefixed by `$' or
-`\'. The following specifiers are recognised:
-
-@table @asis
-@item `@code{$i}'
-Framebuffer index.
-@item `@code{$f}'
-Image filename/pathname.
-Ignored in the filename pattern.
-@item `@code{$n}'
-Image filename.
-Ignored in the filename pattern.
-@item `@code{$p}'
-Image width multiplied by image height.
-@item `@code{$w}'
-Image width.
-@item `@code{$h}'
-Image height.
-@item `@code{$$}'
-Expands to a literal `$'.
-@item `@code{\n}'
-Expands to new line.
-@item `@code{\\}'
-Expands to a literal `\'.
-@item `@code{\ }'
-Expands to a literal ` '.                                           
-@end table
-
-A space that is not prefixed by a backslash in
-@option{--exec} is interpreted as an argument
-delimiter. This is the case even at the beginning
-and end of the string and if a space was the
-previous character in the string.
-
-For example,
-@command{scrotty `%Y-%m-%d_$wx$h.$i.png` --exec 'cp $f ~/.backups/shots/'}
-create a file called something like @file{2014-10-28_1792x1344.0.png}
-for your first framebuffer and @file{2014-10-28_1792x1344.1.png} for
-your second framebuffer, and copies the saved images to @file{~/.backups/shots/}.
-
-
-
-@node strftime
-@chapter @code{strftime}
-
-@command{scrotty} uses @code{strftime}, which
-implemented by the @sc{C} standard library (the
-@sc{GNU} @sc{C} Library for most @sc{GNU}/Linux
-user,) for formatting the filename or commands
-with information about the current date and time.
-If you are using the @sc{GNU} @sc{C} Library,
-full documentation is available in
-@ref{Formatting Calendar Time, Formatting Calendar Time, Formatting Calendar Time, libc, GNU C Library Application Fundamentals}.
-
-Assuming your have a @sc{POSIX}-compliant
-implementation of @code{strftime}, at least the
-following formatters are supported:
-
-@table @code
-@item %a
-The name of weekday in your locale, abbreviated.
-For example `Tue'.
-@item %A
-The name of weekday in your locale. For example
-`Tuesday'.
-@item %b
-@itemx %h
-The name of month in your locale, abbreviated.
-For example `Dec'.
-@item %B
-The name of month in your locale. For example
-`December.
-@item %c
-Your locale's representation for the date and
-time. For example `Tue 08 Dec 2015 09:40:34 CET'.
-@item %C
-The ``century'', or more precisely the year
-divided by 100 and trucated to an integer.
-Between year 2000 and 2099, inclusively, this
-will be `20'.
-@item %d
-The day of the month in two digits. For example,
-`08' during 8 of December.
-@item %D
-Equivalent to @code{%m/%d/%y}. For example
-@code{12/08/15} for 8 of December 2015.
+@setfilename scrotty.info
+@settitle scrotty
+@documentlanguage en_GB
+@include titlepage-data.texinfo
 
-Be aware, this not what expect in most of the
-World, and its requires specialised sorting
-algorithms to be sorted properly. Be also
-aware, that this contains forward slashes, which
-is used as the file delimiter. This is a poor
-idea to use this for the filename. @code{%F}
-is a better choice.
-@item %e
-The day of the month. If only one digit is
-required, it is preceded by a space. For
-example, ` 8' during 8 of December.
-@item %F
-Equivalent to @code{%+4Y-%m-%d}. For example
-@code{2015-12-08} for 8 of December 2015.
-@item %g
-The last 2 digits of the week-based year.
-@item %G
-The week-based year.
-@item %H
-The hour in 24-hour clock format, 2 digits.
-@item %-H
-The hour in 24-hour clock format, as few digits as possible.
-@item %I
-The hour in 12-hour clock format, 2 digits.
-@item %-I
-The hour in 12-hour clock format, as few digits as possible.
-@item %j
-The day of the year in 3 digits.
-For example @code{342} for 8 of December 2015.
-@item %-j
-The day of the year in as few digits as possible.
-@item %m
-The month in 2 digits.
-For example @code{12} for 8 of December 2015.
-@item %-m
-The month in as few digits as possible.
-@item %M
-The minute in 2 digits.
-@item %n
-A new line.
-@item %p
-The locale's repesentation for either ante
-meridiem or post meridiem.
-@item %r
-The time in 12-hour notation. The behaviour
-is not completely specified. You will have
-to try it out. It will probably include
-the second and the timezone.
-@item %R
-The time, in minute resolution, in 24-hour
-notation.@footnote{Yes, this is barely similar to
-@code{%r}.}
-@item %S
-The second, in too digits. Currently leap-seconds
-are not supported, and @sc{POSIX} does not specify
-that double positive leap-seconds are
-possible@footnote{Probably because they are avoided.}.
-@item %t
-A tab space.
-@item %T
-Equivalent to @code{%H:%M:%S}.
-@item %u
-The weekday as a number, starting with Monday as 1.
-@item %U
-The week number of the year, 2 digits.
-The first Sunday of January is the first day of
-week 1. Week 0 is possible.
-@item %-U
-Equivalent to @code{-U}, except in as few digits
-as possible.
-@item %V
-The week number of the year, 2 digits.
-IF week containing 1 of January has at least four
-days in the new year, it is week 1. Week 0 is
-impossible.
-@item %-V
-Equivalent to @code{-V}, except in as few digits
-as possible.
-@item %w
-The weekday as a number, starting with Sunday as 0.
-@item %W
-The week number of the year, 2 digits.
-The first Monday of January is the first day of
-week 1. Week 0 is possible.
-@item %-W
-Equivalent to @code{-W}, except in as few digits
-as possible.
-@item %x
-The locale's representation of the date. This
-may be equivalent or similar to @code{%F} and
-thus a poor idea to use, if so.
-@item %X
-The locale's representation of the time.
-@item %y
-The last two digits in the year. (And at least two digits.)
-@item %Y
-The year with as many digits as necessary.
-@item %z
-The offset of the timezone from UTC. Either
-@code{+hhmm} or @code{-hhmm} (starts with a hyphen.)
-@item %Z
-The name of the timezone, abbreviation.
-@item %%
-A literal `%'.
-@end table
+@c  You can change the title of the document in dir by compiling with
+@c    TEXINFO_FLAGS='--texinfo="@set CATEGORY your_new_category"'
+@ifclear CATEGORY
+@set CATEGORY Multimedia
+@end ifclear
 
-Note, this is not all that @sc{POSIX} specifies,
-but it is the basics. @sc{POSIX} does not specify
-any support for 6-hour clocks, for Saturday as the
-first day of the week (or Tuesay through Friday,) or
-Sunday to be represented by 1 or Monday as 0. If you
-need any of these, you should look into the
-specifications for your @sc{C} standard libraries
-implementation of @code{strftime}, which may or may
-nor support this.
+@dircategory @value{CATEGORY}
+@direntry
+* scrotty: (scrotty).                @value{subtitle}
+@end direntry
 
+@documentdescription
+User manual for scrotty.
+A screenshoter for the framebuffer.
+@end documentdescription
+@c %**end of header
 
 
-@node GNU Free Documentation License
-@appendix GNU Free Documentation License
-@include fdl.texinfo
+@iftex
+@c @set USLETTER
+@c @set AFOURPAPER
+@c @set AFIVEPAPER
+@c @set SMALLBOOK
+
+@c @set HARDCOPY
+@c @set CROPMARKS
+@c @set SKIPCHAPTERNEWPAGE
+@c @set SKIPFONTTEXTSIZE
+@end iftex
+@c @set LOGO
+@c @set DOUBLEHEADINGS
+@c @set SINGLEHEADINGS
+@c @set AMERICANSPACING
+@c @set NOFINALOUT
+
+@ignore
+
+  CROPMARKS has no effect unless HARDCOPY is set. CROPMARKS
+  and AFIVEPAPER (or actually @cropmarks and @afivepaper) does
+  not play well together.
+
+  You can configure how TeX output files should look by uncommenting
+  @set commands above. Do not uncomment more than one of the paper
+  sizes (USLETTER, AFOURPAPER, AFIVEPAPER and SMALLBOOK); if none is
+  uncomment AFOURPAPER will be set unless HARDCOPY is set, in which
+  case SMALLBOOK will be set. However, if you do not want to modify
+  this source file, you can run `make` with for example
+  `TEXINFO_FLAGS='--texinfo="@set HARDCOPY"'`.
+
+  Finally, you can include, on the front page, the version of scrotty
+  that the manual is up to date with, by setting the value of VERSION
+  to the version of scrotty, as well as date of the last update by
+  setting DATE, and edition by setting EDITION. This is intended for
+  printed manuals. The date is recommended to not be more accurate,
+  or less accurate, than to the month. The edition should be formatted
+  as, for example, ``1@sup{st}''.
+
+@end ignore
+
+@comment You can see these too with TEXINFO_FLAGS.
+@c @paragraphindent asis
+@c @firstparagraphindent none
+@c @exampleindent asis
+@c @kbdinputstyle distinct
+
+@include reusable/paper.texinfo
+
+
+@include hardcopy-copying.texinfo
+@include reusable/titlepage.texinfo
+@setheadings{}
+
+@include content.texinfo
 
 @bye