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

  3: #include <petscsys.h>
  4: #include <petscoptions.h>

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

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

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

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

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

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

 39: /*TEST

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

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

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

 93: TEST*/