MagneticField.usage

int usage(int retval, bool brief) {
  if (brief)
    ( retval ? std::cerr : std::cout ) << "Usage:\n"
"    MagneticField [ -n name ] [ -d dir ] [ -N Nmax ] [ -M Mmax ] [ -t time\n"
"    | -c time lat h ] [ -r ] [ -w ] [ -T tguard ] [ -H hguard ] [ -p prec ]\n"
"    [ -v ] [ --comment-delimiter commentdelim ] [ --version | -h | --help ]\n"
"    [ --input-file infile | --input-string instring ] [ --line-separator\n"
"    linesep ] [ --output-file outfile ]\n"
"\n"
"For full documentation type:\n"
"    MagneticField --help\n"
"or visit:\n"
"    https://geographiclib.sourceforge.io/1.50.1/MagneticField.1.html\n";
  else
    ( retval ? std::cerr : std::cout ) << "Man page:\n"
"NAME\n"
"       MagneticField -- compute the earth's magnetic field\n"
"\n"
"SYNOPSIS\n"
"       MagneticField [ -n name ] [ -d dir ] [ -N Nmax ] [ -M Mmax ] [ -t time\n"
"       | -c time lat h ] [ -r ] [ -w ] [ -T tguard ] [ -H hguard ] [ -p prec ]\n"
"       [ -v ] [ --comment-delimiter commentdelim ] [ --version | -h | --help ]\n"
"       [ --input-file infile | --input-string instring ] [ --line-separator\n"
"       linesep ] [ --output-file outfile ]\n"
"\n"
"DESCRIPTION\n"
"       MagneticField reads in times and positions on standard input and prints\n"
"       out the geomagnetic field on standard output and, optionally, its rate\n"
"       of change.\n"
"\n"
"       The input line is of the form time lat lon h. time is a date of the\n"
"       form 2012-07-03, a fractional year such as 2012.5, or the string \"now\".\n"
"       lat and lon are the latitude and longitude expressed as decimal degrees\n"
"       or degrees, minutes, and seconds; for details on the allowed formats\n"
"       for latitude and longitude, see the \"GEOGRAPHIC COORDINATES\" section of\n"
"       GeoConvert(1).  h is the height above the ellipsoid in meters; this is\n"
"       optional and defaults to zero.  Alternatively, time can be given on the\n"
"       command line as the argument to the -t option, in which case it should\n"
"       not be included on the input lines.  Finally, the magnetic field can be\n"
"       computed at various points on a circle of latitude (constant time, lat,\n"
"       and h) via the -c option; in this case only the longitude should be\n"
"       given on the input lines.\n"
"\n"
"       The output consists of the following 7 items:\n"
"\n"
"         the declination (the direction of the horizontal component of\n"
"           the magnetic field measured clockwise from north) in degrees,\n"
"         the inclination (the direction of the magnetic field measured\n"
"           down from the horizontal) in degrees,\n"
"         the horizontal field in nanotesla (nT),\n"
"         the north component of the field in nT,\n"
"         the east component of the field in nT,\n"
"         the vertical component of the field in nT (down is positive),\n"
"         the total field in nT.\n"
"\n"
"       If the -r option is given, a second line is printed giving the rates of\n"
"       change of these quantities in degrees/yr and nT/yr.\n"
"\n"
"       The WGS84 ellipsoid is used, a = 6378137 m, f = 1/298.257223563.\n"
"\n"
"OPTIONS\n"
"       -n name\n"
"           use magnetic field model name instead of the default \"wmm2020\".\n"
"           See \"MODELS\".\n"
"\n"
"       -d dir\n"
"           read magnetic models from dir instead of the default.  See\n"
"           \"MODELS\".\n"
"\n"
"       -N Nmax\n"
"           limit the degree of the model to Nmax.\n"
"\n"
"       -M Mmax\n"
"           limit the order of the model to Mmax.\n"
"\n"
"       -t time\n"
"           evaluate the field at time instead of reading the time from the\n"
"           input lines.\n"
"\n"
"       -c time lat h\n"
"           evaluate the field on a circle of latitude given by time, lat, h\n"
"           instead of reading these quantities from the input lines.  In this\n"
"           case, MagneticField can calculate the field considerably more\n"
"           quickly.\n"
"\n"
"       -r  toggle whether to report the rates of change of the field.\n"
"\n"
"       -w  toggle the longitude first flag (it starts off); if the flag is on,\n"
"           then on input and output, longitude precedes latitude (except that,\n"
"           on input, this can be overridden by a hemisphere designator, N, S,\n"
"           E, W).\n"
"\n"
"       -T tguard\n"
"           signal an error if time lies tguard years (default 50 yr) beyond\n"
"           the range for the model.\n"
"\n"
"       -H hguard\n"
"           signal an error if h lies hguard meters (default 500000 m) beyond\n"
"           the range for the model.\n"
"\n"
"       -p prec\n"
"           set the output precision to prec (default 1).  Fields are printed\n"
"           with precision with prec decimal places; angles use prec + 1\n"
"           places.\n"
"\n"
"       -v  print information about the magnetic model on standard error before\n"
"           processing the input.\n"
"\n"
"       --comment-delimiter commentdelim\n"
"           set the comment delimiter to commentdelim (e.g., \"#\" or \"//\").  If\n"
"           set, the input lines will be scanned for this delimiter and, if\n"
"           found, the delimiter and the rest of the line will be removed prior\n"
"           to processing and subsequently appended to the output line\n"
"           (separated by a space).\n"
"\n"
"       --version\n"
"           print version and exit.\n"
"\n"
"       -h  print usage, the default magnetic path and name, and exit.\n"
"\n"
"       --help\n"
"           print full documentation and exit.\n"
"\n"
"       --input-file infile\n"
"           read input from the file infile instead of from standard input; a\n"
"           file name of \"-\" stands for standard input.\n"
"\n"
"       --input-string instring\n"
"           read input from the string instring instead of from standard input.\n"
"           All occurrences of the line separator character (default is a\n"
"           semicolon) in instring are converted to newlines before the reading\n"
"           begins.\n"
"\n"
"       --line-separator linesep\n"
"           set the line separator character to linesep.  By default this is a\n"
"           semicolon.\n"
"\n"
"       --output-file outfile\n"
"           write output to the file outfile instead of to standard output; a\n"
"           file name of \"-\" stands for standard output.\n"
"\n"
"MODELS\n"
"       MagneticField computes the geomagnetic field using one of the following\n"
"       models\n"
"\n"
"           wmm2010, the World Magnetic Model 2010, which approximates the\n"
"             main magnetic field for the period 2010-2015.  See\n"
"             https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml\n"
"           wmm2015v2, the World Magnetic Model 2015, which approximates the\n"
"             main magnetic field for the period 2015-2020.  See\n"
"             https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml\n"
"           wmm2015, a deprecated version of wmm2015v2\n"
"           wmm2020, the World Magnetic Model 2020, which approximates the\n"
"             main magnetic field for the period 2020-2025.  See\n"
"             https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml\n"
"           igrf11, the International Geomagnetic Reference Field (11th\n"
"             generation), which approximates the main magnetic field for\n"
"             the period 1900-2015.  See\n"
"             https://ngdc.noaa.gov/IAGA/vmod/igrf.html\n"
"           igrf12, the International Geomagnetic Reference Field (12th\n"
"             generation), which approximates the main magnetic field for\n"
"             the period 1900-2020.  See\n"
"             https://ngdc.noaa.gov/IAGA/vmod/igrf.html\n"
"           emm2010, the Enhanced Magnetic Model 2010, which approximates\n"
"             the main and crustal magnetic fields for the period 2010-2015.\n"
"             See https://ngdc.noaa.gov/geomag/EMM/index.html\n"
"           emm2015, the Enhanced Magnetic Model 2015, which approximates\n"
"             the main and crustal magnetic fields for the period 2000-2020.\n"
"             See https://ngdc.noaa.gov/geomag/EMM/index.html\n"
"           emm2017, the Enhanced Magnetic Model 2017, which approximates\n"
"             the main and crustal magnetic fields for the period 2000-2022.\n"
"             See https://ngdc.noaa.gov/geomag/EMM/index.html\n"
"\n"
"       These models approximate the magnetic field due to the earth's core and\n"
"       (in the case of emm20xx) its crust.  They neglect magnetic fields due\n"
"       to the ionosphere, the magnetosphere, nearby magnetized materials,\n"
"       electrical machinery, etc.\n"
"\n"
"       By default, the \"wmm2020\" magnetic model is used.  This may changed by\n"
"       setting the environment variable \"GEOGRAPHICLIB_MAGNETIC_NAME\" or with\n"
"       the -n option.\n"
"\n"
"       The magnetic models will be loaded from a directory specified at\n"
"       compile time.  This may changed by setting the environment variables\n"
"       \"GEOGRAPHICLIB_MAGNETIC_PATH\" or \"GEOGRAPHICLIB_DATA\", or with the -d\n"
"       option.  The -h option prints the default magnetic path and name.  Use\n"
"       the -v option to ascertain the full path name of the data file.\n"
"\n"
"       Instructions for downloading and installing magnetic models are\n"
"       available at\n"
"       <https://geographiclib.sourceforge.io/html/magnetic.html#magneticinst>.\n"
"\n"
"ENVIRONMENT\n"
"       GEOGRAPHICLIB_MAGNETIC_NAME\n"
"           Override the compile-time default magnetic name of \"wmm2020\".  The\n"
"           -h option reports the value of GEOGRAPHICLIB_MAGNETIC_NAME, if\n"
"           defined, otherwise it reports the compile-time value.  If the -n\n"
"           name option is used, then name takes precedence.\n"
"\n"
"       GEOGRAPHICLIB_MAGNETIC_PATH\n"
"           Override the compile-time default magnetic path.  This is typically\n"
"           \"/usr/local/share/GeographicLib/magnetic\" on Unix-like systems and\n"
"           \"C:/ProgramData/GeographicLib/magnetic\" on Windows systems.  The -h\n"
"           option reports the value of GEOGRAPHICLIB_MAGNETIC_PATH, if\n"
"           defined, otherwise it reports the compile-time value.  If the -d\n"
"           dir option is used, then dir takes precedence.\n"
"\n"
"       GEOGRAPHICLIB_DATA\n"
"           Another way of overriding the compile-time default magnetic path.\n"
"           If it is set (and if GEOGRAPHICLIB_MAGNETIC_PATH is not set), then\n"
"           $GEOGRAPHICLIB_DATA/magnetic is used.\n"
"\n"
"ERRORS\n"
"       An illegal line of input will print an error message to standard output\n"
"       beginning with \"ERROR:\" and causes MagneticField to return an exit code\n"
"       of 1.  However, an error does not cause MagneticField to terminate;\n"
"       following lines will be converted.  If time or h are outside the\n"
"       recommended ranges for the model (but inside the ranges increase by\n"
"       tguard and hguard), a warning is printed on standard error and the\n"
"       field (which may be inaccurate) is returned in the normal way.\n"
"\n"
"EXAMPLES\n"
"       The magnetic field from WMM2020 in Timbuktu on 2020-01-01\n"
"\n"
"           echo 2020-01-01 16:46:33N 3:00:34W 300 | MagneticField -r\n"
"           => -1.60 12.00 33973.5 33960.3 -948.1 7223.0 34732.8\n"
"              0.13 -0.02 21.8 23.9 77.9 -8.4 19.5\n"
"\n"
"       The first two numbers returned are the declination and inclination of\n"
"       the field.  The second line gives the annual change.\n"
"\n"
"SEE ALSO\n"
"       GeoConvert(1), geographiclib-get-magnetic(8).\n"
"\n"
"AUTHOR\n"
"       MagneticField was written by Charles Karney.\n"
"\n"
"HISTORY\n"
"       MagneticField was added to GeographicLib,\n"
"       <https://geographiclib.sourceforge.io>, in version 1.15.\n"
;
  return retval;
}