--- sh.platform 2004/01/21 20:40:51 1.4
+++ sh.platform 2004/02/12 16:06:27 1.5
@@ -1,7 +1,6 @@
##
## platform -- Platform Identification Utility
## Copyright (c) 2003-2004 Ralf S. Engelschall <rse@engelschall.com>
-## Originally written for use in OpenPKG
##
## This file is part of shtool and free software; you can redistribute
## it and/or modify it under the terms of the GNU General Public
@@ -20,7 +19,7 @@
##
str_tool="platform"
-str_usage="[-F|--format FORMAT] [-S|--sep STRING] [-C|--conc STRING] [-L|--lower] [-U|--upper] [-v|--verbose] [-c|--concise] [-n|--no-newline] [-t|--type TYPE] [-V|--version] [-h|--help]"
+str_usage="[-F|--format <format>] [-S|--sep <string>] [-C|--conc <string>] [-L|--lower] [-U|--upper] [-v|--verbose] [-c|--concise] [-n|--no-newline] [-t|--type <type>] [-V|--version] [-h|--help]"
arg_spec="0="
opt_spec="F:S:C:L.U.v.c.n.t:d.V.h."
opt_alias="F:format,S:sep,C:conc,L:lower,U:upper,v:verbose,c:consise,t:type,n:no-newline,V:version,h:help"
@@ -572,3 +571,257 @@
echo "$output"
fi
+shtool_exit 0
+
+##
+## manual page
+##
+
+=pod
+
+=head1 NAME
+
+B<shtool platform> - B<GNU shtool> Unix platform identification
+
+=head1 SYNOPSIS
+
+B<shtool platform>
+[B<-F>|B<--format> I<format>]
+[B<-S>|B<--sep> I<string>]
+[B<-C>|B<--conc> I<string>]
+[B<-L>|B<--lower>]
+[B<-U>|B<--upper>]
+[B<-v>|B<--verbose>]
+[B<-c>|B<--concise>]
+[B<-n>|B<--newline>]
+[B<-d>|B<--debug>]
+[B<-t>|B<--type> I<type>]
+[B<-n>|B<--newline>]
+[B<-d>|B<--debug>]
+
+=head1 DESCRIPTION
+
+B<shtool platform> is a flexible Unix platform identification program.
+It distinguishes a platform according to its I<hardware architecture>
+and I<operating system>. For both there is a I<class>, I<product> and
+I<technology> identification. For each of those six identifications,
+there is a I<verbose>, I<regular> and I<concise> version.
+
+This leads to eighteen (2x3x3) available identification strings for each
+platform, from which usually 2 are chosen in a particular situation.
+This is done by assembling the platform identification string using a
+I<format> string containing one or more identification constructs of the
+forms "C<%[xx]>" (verbose), "C<%{xx}>" (regular) and "C<%E<lt>xxE<gt>>"
+(concise).
+
+=head1 OPTIONS
+
+The following command line options are available.
+
+=over 4
+
+=item B<-F>, B<--format> I<format>
+
+This option controls the output formatting of this program. It is a
+plain-text string with the "C<%>I<xx>" constructs which expand to the
+various platform information strings. "C<%{>I<xx>C<}>" is the canonical
+regular version of the information. "C<%[>I<xx>C<]>" is the verbose
+version of the information. "C<%E<lt>>I<xx>C<E<gt>>" is the concise
+version of the information. In total, the following constructs
+are available for expansion:
+
+ %[ac] verbose hardware architecture class
+ %{ac} regular hardware architecture class
+ %<ac> concise hardware architecture class
+
+ %[ap] verbose hardware architecture product
+ %{ap} regular hardware architecture product
+ %<ap> concise hardware architecture product
+
+ %[at] verbose hardware architecture technology
+ %{at} regular hardware architecture technology
+ %<at> concise hardware architecture technology
+
+ %[sc] verbose operating system class
+ %{sc} regular operating system class
+ %<sc> concise operating system class
+
+ %[sp] verbose operating system product
+ %{sp} regular operating system product
+ %<sp> concise operating system product
+
+ %[st] verbose operating system technology
+ %{st} regular operating system technology
+ %<st> concise operating system technology
+
+The default I<format> string is "C<%{sp} (%{ap})>", providing the
+regular operating system and hardware architecture product information.
+
+=item B<-S>, B<--sep> I<string>
+
+This option sets the word I<separation> string for the platform
+information strings. By default it is "C< >" (whitespace). It is
+especially used for separating the operating system name and
+the operating system version.
+
+=item B<-C>, B<--conc> I<string>
+
+This option sets the word I<concatenation> string for the platform
+information strings. By default it is "C</>". It is especially used to
+concatenate multiple parts in operating system name and version parts.
+
+=item B<-L>, B<--lower>
+
+This options enforces conversion of the output to all I<lower> case.
+
+=item B<-U>, B<--upper>
+
+This options enforces conversion of the output to all I<upper> case.
+
+=item B<-v>, B<--verbose>
+
+This option enforces verbose versions of all expansion constructs
+in I<format> string of option B<-F>. It is equal to specifying all
+expansion constructs as "C<%[>I<xx>C<]>".
+
+=item B<-c>, B<--concise>
+
+This option enforces concise versions of all expansion constructs
+in I<format> string of option B<-F>. It is equal to specifying all
+expansion constructs as "C<%E<lt>>I<xx>C<E<gt>>".
+
+=item B<-n>, B<--no-newline>
+
+This option omits the usual trailing newline character in the output.
+
+=item B<-t>, B<--type> I<type>
+
+This option is a meta option which internally sets options B<-F>, B<-S>,
+B<-C>, B<-L>, B<-U>, B<-v> or B<-c> according to I<TYPE>. It can be used
+to easily specify various commonly known outputs. The following I<TYPE>s
+are available:
+
+=over 4
+
+=item B<binary>
+
+Binary Package Id (OpenPKG RPM).
+This is equal to "C<-F '%<ap>-%<sp>' -L -S '' -C '+'>"
+and results in outputs like "C<ix86-freebsd4.9>" and "C<ix86-debian3.0>".
+
+=item B<build>
+
+Build-Time Checking (OpenPKG RPM).
+This is equal to "C<-F '%<at>-%<st>' -L -S '' -C '+'>"
+and results in outputs like "C<i686-freebsd4.9>" and "C<i586-linux2.4>".
+
+=item B<gnu>
+
+GNU F<config.guess> Style Id.
+This is similar to B<build> and is equal to "C<-F '"%<at>-unknown-%<st>' -L -S '' -C '+'>"
+and results in outputs like "C<i686-unknown-freebsd4.9>" and "C<i586-unknown-linux2.4>".
+
+=item B<web>
+
+HTTP Server Header Id.
+This is equal to "C<-F '"%<sp>-%<ac>' -S '/' -C '+'>"
+and results in outputs like "C<FreeBSD/4.9-iX86>" and "C<Debian/3.0-iX86>".
+
+=item B<summary>
+
+Human Readable Verbose Summary Information. This is equal to "C<-F
+'Class: %[sc] (%[ac])\nProduct: %[sp] (%[ap])\nTechnology: %[st]
+(%[at])' -S ' ' -C '/'>" and results in outputs like:
+
+ Class: 4.4BSD (iX86)
+ Product: FreeBSD 4.9-RC (iX86)
+ Technology: FreeBSD 4.9-RC (i686)
+
+and
+
+ Class: LSB (iX86)
+ Product: Debian GNU/Linux 3.0 (iX86)
+ Technology: GNU/Linux 2.2/2.4 (i686)
+
+=item B<all-in-one>
+
+All-In-One Full-Table Information. This just outputs really
+all 2x2x3 identification strings as a table.
+
+=back
+
+=item B<-d>, B<--debug>
+
+This option enables some internal debugging messages.
+
+=item B<-V>, B<--version>
+
+This option outputs the version information of B<shtool platform> only.
+
+=item B<-h>, B<--help>
+
+This option outputs the usage information of B<shtool platform> only.
+
+=back
+
+=head1 EXAMPLE
+
+The following real-life use cases are known:
+
+=over 4
+
+=item B<OpenPKG> build-time decisions
+
+ $ platform -c -L -S "" -C "+" -F "%at-%st"
+ $ platform -c -L -S "" -C "+" -F "%ac-%sc"
+
+=item B<OpenPKG> binary RPM packages
+
+ $ platform -c -L -S "" -C "+" -F "%ap-%sp"
+
+=item F<README> files
+
+ $ platform -v -F "%sp (%ap)"
+ $ platform -v -F "%sc (%ac)"
+
+=item Debugging
+
+ $ platform --type=all-in-one
+
+=back
+
+=head1 SUPPORT
+
+B<shtool platform> currently knows the following particular Unix platforms
+in detail: FreeBSD, NetBSD, OpenBSD, Linux, Sun Solaris, SCO UnixWare,
+QNX Neutrino, SGI IRIX, HP HP-UX, HP Tru64, IBM AIX and Apple MacOS X
+Darwin.
+
+All other Unix platforms are recognized through generic uname(1)
+information and so usually can be identified sufficiently, although the
+identification might be not as precise as possible.
+
+=head1 HISTORY
+
+B<shtool platform> was implemented in September 2003 by I<Ralf S.
+Engelschall> for use in the B<OSSP> and B<OpenPKG> projects. It was
+prompted by the need in B<OpenPKG> to have both product (for RPM
+filenames) and technology (for build-time decisions) identifiers for the
+Unix platforms, OpenPKG packages are maintained for. It was inspired by
+the B<GNU> F<config.guess> and the old B<GNU shtool> F<guessos> command.
+
+The major difference to B<GNU> F<config.guess> is that B<shtool platform>
+does not use a I<vendor> identification (cannot be determined most of
+the time and is not used at all in all projects I've ever seen) and
+is a lot more flexible (class, product and technology identifications
+combined with verbose, regular and concise outputs). The drawback of
+B<shtool platform> is that it (still) knows less particular platforms,
+although the generic platform identification is sufficient enough most
+of the time.
+
+=head1 SEE ALSO
+
+uname(3), GNU F<config.guess>.
+
+=cut
+
|
