1: static char help[] = "Demonstrates restricting the -help output to specific manual sections with -help mansec.\n\n";

  3: #include <petscsys.h>

  5: int main(int argc, char **argv)
  6: {
  7:   PetscReal   r1 = 0., r2 = -1.;
  8:   PetscReal   s1 = 0., s2 = -1.;
  9:   PetscInt    i1 = 0, i2 = -1;
 10:   PetscRandom rnd;

 12:   PetscFunctionBeginUser;
 13:   PetscCall(PetscInitialize(&argc, &argv, NULL, help));

 15:   /* the last argument of PetscOptionsBegin() is the manual section that -help matches against */
 16:   PetscOptionsBegin(PETSC_COMM_WORLD, NULL, "Scaled units options 1", "Sec1");
 17:   PetscCall(PetscOptionsReal("-r1", "r1: real", "ManPage1", r1, &r1, NULL));
 18:   PetscCall(PetscOptionsReal("-s1", "s1: real", "ManPage1", s1, &s1, NULL));
 19:   PetscCall(PetscOptionsInt("-i1", "i1: int", "ManPage1", i1, &i1, NULL));
 20:   PetscOptionsEnd();

 22:   PetscOptionsBegin(PETSC_COMM_WORLD, NULL, "Scaled units options 2", "Sec2");
 23:   PetscCall(PetscOptionsReal("-r2", "r2: real", "ManPage2", r2, &r2, NULL));
 24:   PetscCall(PetscOptionsReal("-s2", "s2: real", "ManPage2", s2, &s2, NULL));
 25:   PetscCall(PetscOptionsInt("-i2", "i2: int", "ManPage2", i2, &i2, NULL));
 26:   PetscOptionsEnd();

 28:   /* PetscRandomSetFromOptions() opens its block with PetscObjectOptionsBegin(), which takes the
 29:      manual section from the object; a PetscRandom carries the Sys section */
 30:   PetscCall(PetscRandomCreate(PETSC_COMM_WORLD, &rnd));
 31:   PetscCall(PetscRandomSetFromOptions(rnd));
 32:   PetscCall(PetscRandomDestroy(&rnd));

 34:   PetscCall(PetscFinalize());
 35:   return 0;
 36: }

 38: /*TEST

 40:    # "-help mansec" restricts the help output to the options blocks in the listed manual section(s);
 41:    # filter to the options blocks to avoid the version banner
 42:    testset:
 43:       filter: grep -E -e "^Scaled units options|\(ManPage[12]\)"
 44:       test:
 45:          suffix: help_sec1
 46:          args: -r1 2 -help Sec1
 47:       test:
 48:          suffix: help_sec1_sec2
 49:          args: -r1 2 -help Sec1,Sec2
 50:       test:
 51:          suffix: help
 52:          args: -help
 53:       # manual sections are matched without regard to case, as PETSc option names are
 54:       test:
 55:          suffix: help_sec1_case
 56:          args: -r1 2 -help sEc1
 57:          output_file: output/ex21_help_sec1.out
 58:       # a man page name is not a manual section, so it selects nothing
 59:       test:
 60:          suffix: help_manpage
 61:          args: -help ManPage1
 62:          output_file: output/empty.out
 63:       # a logical true value is not a manual section; it is equivalent to a bare -help
 64:       test:
 65:          suffix: help_true
 66:          args: -help 1
 67:          output_file: output/ex21_help.out
 68:       # a logical false value turns the help output off; the program runs as if -help had not been given
 69:       test:
 70:          suffix: help_false
 71:          args: -help false
 72:          output_file: output/empty.out

 74:    # blocks opened with PetscObjectOptionsBegin() take their manual section from the object
 75:    test:
 76:       suffix: help_object
 77:       args: -help Sys
 78:       filter: grep -E -e "^Random number generator|\(PetscRandomSetSeed\)"

 80:    # the viewer options of an object are documented in the Viewer section, not in the section of the
 81:    # object that creates them, so they are not selected along with it
 82:    test:
 83:       suffix: help_sys_no_viewer
 84:       args: -help Sys
 85:       filter: grep -E -e "^Viewer \("
 86:       output_file: output/empty.out
 87:    test:
 88:       suffix: help_viewer
 89:       args: -help Viewer
 90:       filter: grep -E -e "^Viewer \(-random_view\)"

 92: TEST*/