Commit ab9f4cc212d03c2716a9144dcd4b11db330112ef
1 parent
2e342ee5
Split help string
It was too long for some compilers.
Showing
1 changed file
with
339 additions
and
344 deletions
qpdf/qpdf.cc
| ... | ... | @@ -646,8 +646,6 @@ class ArgParser |
| 646 | 646 | std::vector<int> parseNumrange(char const* range, int max, |
| 647 | 647 | bool throw_error = false); |
| 648 | 648 | |
| 649 | - static char const* help; | |
| 650 | - | |
| 651 | 649 | int argc; |
| 652 | 650 | char** argv; |
| 653 | 651 | Options& o; |
| ... | ... | @@ -939,7 +937,345 @@ ArgParser::argCopyright() |
| 939 | 937 | void |
| 940 | 938 | ArgParser::argHelp() |
| 941 | 939 | { |
| 942 | - std::cout << help; | |
| 940 | + std::cout | |
| 941 | + // 12345678901234567890123456789012345678901234567890123456789012345678901234567890 | |
| 942 | + << "Usage: qpdf [ options ] { infilename | --empty } [ outfilename ]\n" | |
| 943 | + << "\n" | |
| 944 | + << "An option summary appears below. Please see the documentation for details.\n" | |
| 945 | + << "\n" | |
| 946 | + << "If @filename appears anywhere in the command-line, each line of filename\n" | |
| 947 | + << "will be interpreted as an argument. No interpolation is done. Line\n" | |
| 948 | + << "terminators are stripped. @- can be specified to read from standard input.\n" | |
| 949 | + << "\n" | |
| 950 | + << "Note that when contradictory options are provided, whichever options are\n" | |
| 951 | + << "provided last take precedence.\n" | |
| 952 | + << "\n" | |
| 953 | + << "\n" | |
| 954 | + << "Basic Options\n" | |
| 955 | + << "-------------\n" | |
| 956 | + << "\n" | |
| 957 | + << "--version show version of qpdf\n" | |
| 958 | + << "--copyright show qpdf's copyright and license information\n" | |
| 959 | + << "--help show command-line argument help\n" | |
| 960 | + << "--completion-bash output a bash complete command you can eval\n" | |
| 961 | + << "--completion-zsh output a zsh complete command you can eval\n" | |
| 962 | + << "--password=password specify a password for accessing encrypted files\n" | |
| 963 | + << "--verbose provide additional informational output\n" | |
| 964 | + << "--progress give progress indicators while writing output\n" | |
| 965 | + << "--no-warn suppress warnings\n" | |
| 966 | + << "--linearize generated a linearized (web optimized) file\n" | |
| 967 | + << "--copy-encryption=file copy encryption parameters from specified file\n" | |
| 968 | + << "--encryption-file-password=password\n" | |
| 969 | + << " password used to open the file from which encryption\n" | |
| 970 | + << " parameters are being copied\n" | |
| 971 | + << "--encrypt options -- generate an encrypted file\n" | |
| 972 | + << "--decrypt remove any encryption on the file\n" | |
| 973 | + << "--password-is-hex-key treat primary password option as a hex-encoded key\n" | |
| 974 | + << "--pages options -- select specific pages from one or more files\n" | |
| 975 | + << "--collate causes files specified in --pages to be collated\n" | |
| 976 | + << " rather than concatenated\n" | |
| 977 | + << "--rotate=[+|-]angle[:page-range]\n" | |
| 978 | + << " rotate each specified page 90, 180, or 270 degrees;\n" | |
| 979 | + << " rotate all pages if no page range is given\n" | |
| 980 | + << "--split-pages=[n] write each output page to a separate file\n" | |
| 981 | + << "\n" | |
| 982 | + << "Note that you can use the @filename or @- syntax for any argument at any\n" | |
| 983 | + << "point in the command. This provides a good way to specify a password without\n" | |
| 984 | + << "having to explicitly put it on the command line.\n" | |
| 985 | + << "\n" | |
| 986 | + << "If none of --copy-encryption, --encrypt or --decrypt are given, qpdf will\n" | |
| 987 | + << "preserve any encryption data associated with a file.\n" | |
| 988 | + << "\n" | |
| 989 | + << "Note that when copying encryption parameters from another file, all\n" | |
| 990 | + << "parameters will be copied, including both user and owner passwords, even\n" | |
| 991 | + << "if the user password is used to open the other file. This works even if\n" | |
| 992 | + << "the owner password is not known.\n" | |
| 993 | + << "\n" | |
| 994 | + << "The --password-is-hex-key option overrides the normal computation of\n" | |
| 995 | + << "encryption keys. It only applies to the password used to open the main\n" | |
| 996 | + << "file. This option is not ordinarily useful but can be helpful for forensic\n" | |
| 997 | + << "or investigatory purposes. See manual for further discussion.\n" | |
| 998 | + << "\n" | |
| 999 | + << "The --rotate flag can be used to specify pages to rotate pages either\n" | |
| 1000 | + << "90, 180, or 270 degrees. The page range is specified in the same\n" | |
| 1001 | + << "format as with the --pages option, described below. Repeat the option\n" | |
| 1002 | + << "to rotate multiple groups of pages. If the angle is preceded by + or -,\n" | |
| 1003 | + << "it is added to or subtracted from the original rotation. Otherwise, the\n" | |
| 1004 | + << "rotation angle is set explicitly to the given value.\n" | |
| 1005 | + << "\n" | |
| 1006 | + << "If --split-pages is specified, each page is written to a separate output\n" | |
| 1007 | + << "file. File names are generated as follows:\n" | |
| 1008 | + << "* If the string %d appears in the output file name, it is replaced with a\n" | |
| 1009 | + << " zero-padded page range starting from 1\n" | |
| 1010 | + << "* Otherwise, if the output file name ends in .pdf (case insensitive), a\n" | |
| 1011 | + << " zero-padded page range, preceded by a dash, is inserted before the file\n" | |
| 1012 | + << " extension\n" | |
| 1013 | + << "* Otherwise, the file name is appended with a zero-padded page range\n" | |
| 1014 | + << " preceded by a dash.\n" | |
| 1015 | + << "Page ranges are single page numbers for single-page groups or first-last\n" | |
| 1016 | + << "for multipage groups.\n" | |
| 1017 | + << "\n" | |
| 1018 | + << "\n" | |
| 1019 | + << "Encryption Options\n" | |
| 1020 | + << "------------------\n" | |
| 1021 | + << "\n" | |
| 1022 | + << " --encrypt user-password owner-password key-length flags --\n" | |
| 1023 | + << "\n" | |
| 1024 | + << "Note that -- terminates parsing of encryption flags.\n" | |
| 1025 | + << "\n" | |
| 1026 | + << "Either or both of the user password and the owner password may be\n" | |
| 1027 | + << "empty strings.\n" | |
| 1028 | + << "\n" | |
| 1029 | + << "key-length may be 40, 128, or 256\n" | |
| 1030 | + << "\n" | |
| 1031 | + << "Additional flags are dependent upon key length.\n" | |
| 1032 | + << "\n" | |
| 1033 | + << " If 40:\n" | |
| 1034 | + << "\n" | |
| 1035 | + << " --print=[yn] allow printing\n" | |
| 1036 | + << " --modify=[yn] allow document modification\n" | |
| 1037 | + << " --extract=[yn] allow text/graphic extraction\n" | |
| 1038 | + << " --annotate=[yn] allow comments and form fill-in and signing\n" | |
| 1039 | + << "\n" | |
| 1040 | + << " If 128:\n" | |
| 1041 | + << "\n" | |
| 1042 | + << " --accessibility=[yn] allow accessibility to visually impaired\n" | |
| 1043 | + << " --extract=[yn] allow other text/graphic extraction\n" | |
| 1044 | + << " --print=print-opt control printing access\n" | |
| 1045 | + << " --modify=modify-opt control modify access\n" | |
| 1046 | + << " --cleartext-metadata prevents encryption of metadata\n" | |
| 1047 | + << " --use-aes=[yn] indicates whether to use AES encryption\n" | |
| 1048 | + << " --force-V4 forces use of V=4 encryption handler\n" | |
| 1049 | + << "\n" | |
| 1050 | + << " If 256, options are the same as 128 with these exceptions:\n" | |
| 1051 | + << " --force-V4 this option is not available with 256-bit keys\n" | |
| 1052 | + << " --use-aes this option is always on with 256-bit keys\n" | |
| 1053 | + << " --force-R5 forces use of deprecated R=5 encryption\n" | |
| 1054 | + << "\n" | |
| 1055 | + << " print-opt may be:\n" | |
| 1056 | + << "\n" | |
| 1057 | + << " full allow full printing\n" | |
| 1058 | + << " low allow only low-resolution printing\n" | |
| 1059 | + << " none disallow printing\n" | |
| 1060 | + << "\n" | |
| 1061 | + << " modify-opt may be:\n" | |
| 1062 | + << "\n" | |
| 1063 | + << " all allow full document modification\n" | |
| 1064 | + << " annotate allow comment authoring and form operations\n" | |
| 1065 | + << " form allow form field fill-in and signing\n" | |
| 1066 | + << " assembly allow document assembly only\n" | |
| 1067 | + << " none allow no modifications\n" | |
| 1068 | + << "\n" | |
| 1069 | + << "The default for each permission option is to be fully permissive.\n" | |
| 1070 | + << "\n" | |
| 1071 | + << "Specifying cleartext-metadata forces the PDF version to at least 1.5.\n" | |
| 1072 | + << "Specifying use of AES forces the PDF version to at least 1.6. These\n" | |
| 1073 | + << "options are both off by default.\n" | |
| 1074 | + << "\n" | |
| 1075 | + << "The --force-V4 flag forces the V=4 encryption handler introduced in PDF 1.5\n" | |
| 1076 | + << "to be used even if not otherwise needed. This option is primarily useful\n" | |
| 1077 | + << "for testing qpdf and has no other practical use.\n" | |
| 1078 | + << "\n" | |
| 1079 | + << "\n" | |
| 1080 | + << "Page Selection Options\n" | |
| 1081 | + << "----------------------\n" | |
| 1082 | + << "\n" | |
| 1083 | + << "These options allow pages to be selected from one or more PDF files.\n" | |
| 1084 | + << "Whatever file is given as the primary input file is used as the\n" | |
| 1085 | + << "starting point, but its pages are replaced with pages as specified.\n" | |
| 1086 | + << "\n" | |
| 1087 | + << "--keep-files-open=[yn]\n" | |
| 1088 | + << "--pages file [ --password=password ] [ page-range ] ... --\n" | |
| 1089 | + << "\n" | |
| 1090 | + << "For each file that pages should be taken from, specify the file, a\n" | |
| 1091 | + << "password needed to open the file (if any), and a page range. The\n" | |
| 1092 | + << "password needs to be given only once per file. If any of the input\n" | |
| 1093 | + << "files are the same as the primary input file or the file used to copy\n" | |
| 1094 | + << "encryption parameters (if specified), you do not need to repeat the\n" | |
| 1095 | + << "password here. The same file can be repeated multiple times. All\n" | |
| 1096 | + << "non-page data (info, outlines, page numbers, etc. are taken from the\n" | |
| 1097 | + << "primary input file. To discard this, use --empty as the primary\n" | |
| 1098 | + << "input.\n" | |
| 1099 | + << "\n" | |
| 1100 | + << "By default, when more than 200 distinct files are specified, qpdf will\n" | |
| 1101 | + << "close each file when not being referenced. With 200 files or fewer, all\n" | |
| 1102 | + << "files will be kept open at the same time. This behavior can be overridden\n" | |
| 1103 | + << "by specifying --keep-files-open=[yn]. Closing and opening files can have\n" | |
| 1104 | + << "very high overhead on certain file systems, especially networked file\n" | |
| 1105 | + << "systems.\n" | |
| 1106 | + << "\n" | |
| 1107 | + << "The page range is a set of numbers separated by commas, ranges of\n" | |
| 1108 | + << "numbers separated dashes, or combinations of those. The character\n" | |
| 1109 | + << "\"z\" represents the last page. A number preceded by an \"r\" indicates\n" | |
| 1110 | + << "to count from the end, so \"r3-r1\" would be the last three pages of the\n" | |
| 1111 | + << "document. Pages can appear in any order. Ranges can appear with a\n" | |
| 1112 | + << "high number followed by a low number, which causes the pages to appear in\n" | |
| 1113 | + << "reverse. Repeating a number will cause an error, but the manual discusses\n" | |
| 1114 | + << "a workaround should you really want to include the same page twice.\n" | |
| 1115 | + << "\n" | |
| 1116 | + << "If the page range is omitted, the range of 1-z is assumed. qpdf decides\n" | |
| 1117 | + << "that the page range is omitted if the range argument is either -- or a\n" | |
| 1118 | + << "valid file name and not a valid range.\n" | |
| 1119 | + << "\n" | |
| 1120 | + << "The usual behavior of --pages is to add all pages from the first file,\n" | |
| 1121 | + << "then all pages from the second file, and so on. If the --collate option\n" | |
| 1122 | + << "is specified, then pages are collated instead. In other words, qpdf takes\n" | |
| 1123 | + << "the first page from the first file, the first page from the second file,\n" | |
| 1124 | + << "and so on until it runs out of files; then it takes the second page from\n" | |
| 1125 | + << "each file, etc. When a file runs out of pages, it is skipped until all\n" | |
| 1126 | + << "specified pages are taken from all files.\n" | |
| 1127 | + << "\n" | |
| 1128 | + << "See the manual for examples and a discussion of additional subtleties.\n" | |
| 1129 | + << "\n" | |
| 1130 | + << "\n" | |
| 1131 | + << "Advanced Parsing Options\n" | |
| 1132 | + << "-------------------------------\n" | |
| 1133 | + << "\n" | |
| 1134 | + << "These options control aspects of how qpdf reads PDF files. Mostly these are\n" | |
| 1135 | + << "of use to people who are working with damaged files. There is little reason\n" | |
| 1136 | + << "to use these options unless you are trying to solve specific problems.\n" | |
| 1137 | + << "\n" | |
| 1138 | + << "--suppress-recovery prevents qpdf from attempting to recover damaged files\n" | |
| 1139 | + << "--ignore-xref-streams tells qpdf to ignore any cross-reference streams\n" | |
| 1140 | + << "\n" | |
| 1141 | + << "\n" | |
| 1142 | + << "Advanced Transformation Options\n" | |
| 1143 | + << "-------------------------------\n" | |
| 1144 | + << "\n" | |
| 1145 | + << "These transformation options control fine points of how qpdf creates\n" | |
| 1146 | + << "the output file. Mostly these are of use only to people who are very\n" | |
| 1147 | + << "familiar with the PDF file format or who are PDF developers.\n" | |
| 1148 | + << "\n" | |
| 1149 | + << "--stream-data=option controls transformation of stream data (below)\n" | |
| 1150 | + << "--compress-streams=[yn] controls whether to compress streams on output\n" | |
| 1151 | + << "--decode-level=option controls how to filter streams from the input\n" | |
| 1152 | + << "--normalize-content=[yn] enables or disables normalization of content streams\n" | |
| 1153 | + << "--object-streams=mode controls handing of object streams\n" | |
| 1154 | + << "--preserve-unreferenced preserve unreferenced objects\n" | |
| 1155 | + << "--preserve-unreferenced-resources\n" | |
| 1156 | + << " preserve unreferenced page resources\n" | |
| 1157 | + << "--newline-before-endstream always put a newline before endstream\n" | |
| 1158 | + << "--coalesce-contents force all pages' content to be a single stream\n" | |
| 1159 | + << "--flatten-annotations=option\n" | |
| 1160 | + << " incorporate rendering of annotations into page\n" | |
| 1161 | + << " contents including those for interactive form\n" | |
| 1162 | + << " fields; may also want --generate-appearances\n" | |
| 1163 | + << "--generate-appearances generate appearance streams for form fields\n" | |
| 1164 | + << "--optimize-images compress images with DCT (JPEG) when advantageous\n" | |
| 1165 | + << "--oi-min-width=w do not optimize images whose width is below w\n" | |
| 1166 | + << "--oi-min-height=h do not optimize images whose height is below h\n" | |
| 1167 | + << "--oi-min-area=a do not optimize images whose pixel count is below a\n" | |
| 1168 | + << "--qdf turns on \"QDF mode\" (below)\n" | |
| 1169 | + << "--linearize-pass1=file write intermediate pass of linearized file\n" | |
| 1170 | + << " for debugging\n" | |
| 1171 | + << "--min-version=version sets the minimum PDF version of the output file\n" | |
| 1172 | + << "--force-version=version forces this to be the PDF version of the output file\n" | |
| 1173 | + << "\n" | |
| 1174 | + << "Options for --flatten-annotations are all, print, or screen. If the option\n" | |
| 1175 | + << "is print, only annotations marked as print are included. If the option is\n" | |
| 1176 | + << "screen, options marked as \"no view\" are excluded. Otherwise, annotations\n" | |
| 1177 | + << "are flattened regardless of the presence of print or NoView flags. It is\n" | |
| 1178 | + << "common for PDF files to have a flag set that appearance streams need to be\n" | |
| 1179 | + << "regenerated. This happens when someone changes a form value with software\n" | |
| 1180 | + << "that does not know how to render the new value. qpdf will not flatten form\n" | |
| 1181 | + << "fields in files like this. If you get this warning, you have two choices:\n" | |
| 1182 | + << "either use qpdf's --generate-appearances flag to tell qpdf to go ahead and\n" | |
| 1183 | + << "regenerate appearances, or use some other tool to generate the appearances.\n" | |
| 1184 | + << "qpdf does a pretty good job with most forms when only ASCII characters are\n" | |
| 1185 | + << "used in form field values, but if your form fields contain other\n" | |
| 1186 | + << "characters, rich text, or are other than left justified, you will get\n" | |
| 1187 | + << "better results first saving with other software.\n" | |
| 1188 | + << "\n" | |
| 1189 | + << "Version numbers may be expressed as major.minor.extension-level, so 1.7.3\n" | |
| 1190 | + << "means PDF version 1.7 at extension level 3.\n" | |
| 1191 | + << "\n" | |
| 1192 | + << "Values for stream data options:\n" | |
| 1193 | + << "\n" | |
| 1194 | + << " compress recompress stream data when possible (default)\n" | |
| 1195 | + << " preserve leave all stream data as is\n" | |
| 1196 | + << " uncompress uncompress stream data when possible\n" | |
| 1197 | + << "\n" | |
| 1198 | + << "Values for object stream mode:\n" | |
| 1199 | + << "\n" | |
| 1200 | + << " preserve preserve original object streams (default)\n" | |
| 1201 | + << " disable don't write any object streams\n" | |
| 1202 | + << " generate use object streams wherever possible\n" | |
| 1203 | + << "\n" | |
| 1204 | + << "When --compress-streams=n is specified, this overrides the default behavior\n" | |
| 1205 | + << "of qpdf, which is to attempt compress uncompressed streams. Setting\n" | |
| 1206 | + << "stream data mode to uncompress or preserve has the same effect.\n" | |
| 1207 | + << "\n" | |
| 1208 | + << "The --decode-level parameter may be set to one of the following values:\n" | |
| 1209 | + << " none do not decode streams\n" | |
| 1210 | + << " generalized decode streams compressed with generalized filters\n" | |
| 1211 | + << " including LZW, Flate, and the ASCII encoding filters.\n" | |
| 1212 | + << " specialized additionally decode streams with non-lossy specialized\n" | |
| 1213 | + << " filters including RunLength\n" | |
| 1214 | + << " all additionally decode streams with lossy filters\n" | |
| 1215 | + << " including DCT (JPEG)\n" | |
| 1216 | + << "\n" | |
| 1217 | + << "In qdf mode, by default, content normalization is turned on, and the\n" | |
| 1218 | + << "stream data mode is set to uncompress.\n" | |
| 1219 | + << "\n" | |
| 1220 | + << "Setting the minimum PDF version of the output file may raise the version\n" | |
| 1221 | + << "but will never lower it. Forcing the PDF version of the output file may\n" | |
| 1222 | + << "set the PDF version to a lower value than actually allowed by the file's\n" | |
| 1223 | + << "contents. You should only do this if you have no other possible way to\n" | |
| 1224 | + << "open the file or if you know that the file definitely doesn't include\n" | |
| 1225 | + << "features not supported later versions.\n" | |
| 1226 | + << "\n" | |
| 1227 | + << "Testing, Inspection, and Debugging Options\n" | |
| 1228 | + << "------------------------------------------\n" | |
| 1229 | + << "\n" | |
| 1230 | + << "These options can be useful for digging into PDF files or for use in\n" | |
| 1231 | + << "automated test suites for software that uses the qpdf library.\n" | |
| 1232 | + << "\n" | |
| 1233 | + << "--deterministic-id generate deterministic /ID\n" | |
| 1234 | + << "--static-id generate static /ID: FOR TESTING ONLY!\n" | |
| 1235 | + << "--static-aes-iv use a static initialization vector for AES-CBC\n" | |
| 1236 | + << " This is option is not secure! FOR TESTING ONLY!\n" | |
| 1237 | + << "--no-original-object-ids suppress original object ID comments in qdf mode\n" | |
| 1238 | + << "--show-encryption quickly show encryption parameters\n" | |
| 1239 | + << "--show-encryption-key when showing encryption, reveal the actual key\n" | |
| 1240 | + << "--check-linearization check file integrity and linearization status\n" | |
| 1241 | + << "--show-linearization check and show all linearization data\n" | |
| 1242 | + << "--show-xref show the contents of the cross-reference table\n" | |
| 1243 | + << "--show-object=trailer|obj[,gen]\n" | |
| 1244 | + << " show the contents of the given object\n" | |
| 1245 | + << " --raw-stream-data show raw stream data instead of object contents\n" | |
| 1246 | + << " --filtered-stream-data show filtered stream data instead of object contents\n" | |
| 1247 | + << "--show-npages print the number of pages in the file\n" | |
| 1248 | + << "--show-pages shows the object/generation number for each page\n" | |
| 1249 | + << " --with-images also shows the object IDs for images on each page\n" | |
| 1250 | + << "--check check file structure + encryption, linearization\n" | |
| 1251 | + << "--json generate a json representation of the file\n" | |
| 1252 | + << "--json-help describe the format of the json representation\n" | |
| 1253 | + << "--json-key=key repeatable; prune json structure to include only\n" | |
| 1254 | + << " specified keys. If absent, all keys are shown\n" | |
| 1255 | + << "--json-object=trailer|[obj,gen]\n" | |
| 1256 | + << " repeatable; include only specified objects in the\n" | |
| 1257 | + << " \"objects\" section of the json. If absent, all\n" | |
| 1258 | + << " objects are shown\n" | |
| 1259 | + << "\n" | |
| 1260 | + << "The json representation generated by qpdf is designed to facilitate\n" | |
| 1261 | + << "processing of qpdf from other programming languages that have a hard\n" | |
| 1262 | + << "time calling C++ APIs. Run qpdf --json-help for details on the format.\n" | |
| 1263 | + << "The manual has more in-depth information about the json representation\n" | |
| 1264 | + << "and certain compatibility guarantees that qpdf provides.\n" | |
| 1265 | + << "\n" | |
| 1266 | + << "The --raw-stream-data and --filtered-stream-data options are ignored\n" | |
| 1267 | + << "unless --show-object is given. Either of these options will cause the\n" | |
| 1268 | + << "stream data to be written to standard output.\n" | |
| 1269 | + << "\n" | |
| 1270 | + << "If --filtered-stream-data is given and --normalize-content=y is also\n" | |
| 1271 | + << "given, qpdf will attempt to normalize the stream data as if it is a\n" | |
| 1272 | + << "page content stream. This attempt will be made even if it is not a\n" | |
| 1273 | + << "page content stream, in which case it will produce unusable results.\n" | |
| 1274 | + << "\n" | |
| 1275 | + << "Ordinarily, qpdf exits with a status of 0 on success or a status of 2\n" | |
| 1276 | + << "if any errors occurred. If there were warnings but not errors, qpdf\n" | |
| 1277 | + << "exits with a status of 3. If warnings would have been issued but --no-warn\n" | |
| 1278 | + << "was given, an exit status of 3 is still used.\n"; | |
| 943 | 1279 | } |
| 944 | 1280 | |
| 945 | 1281 | void |
| ... | ... | @@ -1732,347 +2068,6 @@ ArgParser::handleBashArguments() |
| 1732 | 2068 | argv[argc] = 0; |
| 1733 | 2069 | } |
| 1734 | 2070 | |
| 1735 | -char const* ArgParser::help = "\ | |
| 1736 | -\n\ | |
| 1737 | -Usage: qpdf [ options ] { infilename | --empty } [ outfilename ]\n\ | |
| 1738 | -\n\ | |
| 1739 | -An option summary appears below. Please see the documentation for details.\n\ | |
| 1740 | -\n\ | |
| 1741 | -If @filename appears anywhere in the command-line, each line of filename\n\ | |
| 1742 | -will be interpreted as an argument. No interpolation is done. Line\n\ | |
| 1743 | -terminators are stripped. @- can be specified to read from standard input.\n\ | |
| 1744 | -\n\ | |
| 1745 | -Note that when contradictory options are provided, whichever options are\n\ | |
| 1746 | -provided last take precedence.\n\ | |
| 1747 | -\n\ | |
| 1748 | -\n\ | |
| 1749 | -Basic Options\n\ | |
| 1750 | --------------\n\ | |
| 1751 | -\n\ | |
| 1752 | ---version show version of qpdf\n\ | |
| 1753 | ---copyright show qpdf's copyright and license information\n\ | |
| 1754 | ---help show command-line argument help\n\ | |
| 1755 | ---completion-bash output a bash complete command you can eval\n\ | |
| 1756 | ---completion-zsh output a zsh complete command you can eval\n\ | |
| 1757 | ---password=password specify a password for accessing encrypted files\n\ | |
| 1758 | ---verbose provide additional informational output\n\ | |
| 1759 | ---progress give progress indicators while writing output\n\ | |
| 1760 | ---no-warn suppress warnings\n\ | |
| 1761 | ---linearize generated a linearized (web optimized) file\n\ | |
| 1762 | ---copy-encryption=file copy encryption parameters from specified file\n\ | |
| 1763 | ---encryption-file-password=password\n\ | |
| 1764 | - password used to open the file from which encryption\n\ | |
| 1765 | - parameters are being copied\n\ | |
| 1766 | ---encrypt options -- generate an encrypted file\n\ | |
| 1767 | ---decrypt remove any encryption on the file\n\ | |
| 1768 | ---password-is-hex-key treat primary password option as a hex-encoded key\n\ | |
| 1769 | ---pages options -- select specific pages from one or more files\n\ | |
| 1770 | ---collate causes files specified in --pages to be collated\n\ | |
| 1771 | - rather than concatenated\n\ | |
| 1772 | ---rotate=[+|-]angle[:page-range]\n\ | |
| 1773 | - rotate each specified page 90, 180, or 270 degrees;\n\ | |
| 1774 | - rotate all pages if no page range is given\n\ | |
| 1775 | ---split-pages=[n] write each output page to a separate file\n\ | |
| 1776 | -\n\ | |
| 1777 | -Note that you can use the @filename or @- syntax for any argument at any\n\ | |
| 1778 | -point in the command. This provides a good way to specify a password without\n\ | |
| 1779 | -having to explicitly put it on the command line.\n\ | |
| 1780 | -\n\ | |
| 1781 | -If none of --copy-encryption, --encrypt or --decrypt are given, qpdf will\n\ | |
| 1782 | -preserve any encryption data associated with a file.\n\ | |
| 1783 | -\n\ | |
| 1784 | -Note that when copying encryption parameters from another file, all\n\ | |
| 1785 | -parameters will be copied, including both user and owner passwords, even\n\ | |
| 1786 | -if the user password is used to open the other file. This works even if\n\ | |
| 1787 | -the owner password is not known.\n\ | |
| 1788 | -\n\ | |
| 1789 | -The --password-is-hex-key option overrides the normal computation of\n\ | |
| 1790 | -encryption keys. It only applies to the password used to open the main\n\ | |
| 1791 | -file. This option is not ordinarily useful but can be helpful for forensic\n\ | |
| 1792 | -or investigatory purposes. See manual for further discussion.\n\ | |
| 1793 | -\n\ | |
| 1794 | -The --rotate flag can be used to specify pages to rotate pages either\n\ | |
| 1795 | -90, 180, or 270 degrees. The page range is specified in the same\n\ | |
| 1796 | -format as with the --pages option, described below. Repeat the option\n\ | |
| 1797 | -to rotate multiple groups of pages. If the angle is preceded by + or -,\n\ | |
| 1798 | -it is added to or subtracted from the original rotation. Otherwise, the\n\ | |
| 1799 | -rotation angle is set explicitly to the given value.\n\ | |
| 1800 | -\n\ | |
| 1801 | -If --split-pages is specified, each page is written to a separate output\n\ | |
| 1802 | -file. File names are generated as follows:\n\ | |
| 1803 | -* If the string %d appears in the output file name, it is replaced with a\n\ | |
| 1804 | - zero-padded page range starting from 1\n\ | |
| 1805 | -* Otherwise, if the output file name ends in .pdf (case insensitive), a\n\ | |
| 1806 | - zero-padded page range, preceded by a dash, is inserted before the file\n\ | |
| 1807 | - extension\n\ | |
| 1808 | -* Otherwise, the file name is appended with a zero-padded page range\n\ | |
| 1809 | - preceded by a dash.\n\ | |
| 1810 | -Page ranges are single page numbers for single-page groups or first-last\n\ | |
| 1811 | -for multipage groups.\n\ | |
| 1812 | -\n\ | |
| 1813 | -\n\ | |
| 1814 | -Encryption Options\n\ | |
| 1815 | -------------------\n\ | |
| 1816 | -\n\ | |
| 1817 | - --encrypt user-password owner-password key-length flags --\n\ | |
| 1818 | -\n\ | |
| 1819 | -Note that -- terminates parsing of encryption flags.\n\ | |
| 1820 | -\n\ | |
| 1821 | -Either or both of the user password and the owner password may be\n\ | |
| 1822 | -empty strings.\n\ | |
| 1823 | -\n\ | |
| 1824 | -key-length may be 40, 128, or 256\n\ | |
| 1825 | -\n\ | |
| 1826 | -Additional flags are dependent upon key length.\n\ | |
| 1827 | -\n\ | |
| 1828 | - If 40:\n\ | |
| 1829 | -\n\ | |
| 1830 | - --print=[yn] allow printing\n\ | |
| 1831 | - --modify=[yn] allow document modification\n\ | |
| 1832 | - --extract=[yn] allow text/graphic extraction\n\ | |
| 1833 | - --annotate=[yn] allow comments and form fill-in and signing\n\ | |
| 1834 | -\n\ | |
| 1835 | - If 128:\n\ | |
| 1836 | -\n\ | |
| 1837 | - --accessibility=[yn] allow accessibility to visually impaired\n\ | |
| 1838 | - --extract=[yn] allow other text/graphic extraction\n\ | |
| 1839 | - --print=print-opt control printing access\n\ | |
| 1840 | - --modify=modify-opt control modify access\n\ | |
| 1841 | - --cleartext-metadata prevents encryption of metadata\n\ | |
| 1842 | - --use-aes=[yn] indicates whether to use AES encryption\n\ | |
| 1843 | - --force-V4 forces use of V=4 encryption handler\n\ | |
| 1844 | -\n\ | |
| 1845 | - If 256, options are the same as 128 with these exceptions:\n\ | |
| 1846 | - --force-V4 this option is not available with 256-bit keys\n\ | |
| 1847 | - --use-aes this option is always on with 256-bit keys\n\ | |
| 1848 | - --force-R5 forces use of deprecated R=5 encryption\n\ | |
| 1849 | -\n\ | |
| 1850 | - print-opt may be:\n\ | |
| 1851 | -\n\ | |
| 1852 | - full allow full printing\n\ | |
| 1853 | - low allow only low-resolution printing\n\ | |
| 1854 | - none disallow printing\n\ | |
| 1855 | -\n\ | |
| 1856 | - modify-opt may be:\n\ | |
| 1857 | -\n\ | |
| 1858 | - all allow full document modification\n\ | |
| 1859 | - annotate allow comment authoring and form operations\n\ | |
| 1860 | - form allow form field fill-in and signing\n\ | |
| 1861 | - assembly allow document assembly only\n\ | |
| 1862 | - none allow no modifications\n\ | |
| 1863 | -\n\ | |
| 1864 | -The default for each permission option is to be fully permissive.\n\ | |
| 1865 | -\n\ | |
| 1866 | -Specifying cleartext-metadata forces the PDF version to at least 1.5.\n\ | |
| 1867 | -Specifying use of AES forces the PDF version to at least 1.6. These\n\ | |
| 1868 | -options are both off by default.\n\ | |
| 1869 | -\n\ | |
| 1870 | -The --force-V4 flag forces the V=4 encryption handler introduced in PDF 1.5\n\ | |
| 1871 | -to be used even if not otherwise needed. This option is primarily useful\n\ | |
| 1872 | -for testing qpdf and has no other practical use.\n\ | |
| 1873 | -\n\ | |
| 1874 | -\n\ | |
| 1875 | -Page Selection Options\n\ | |
| 1876 | -----------------------\n\ | |
| 1877 | -\n\ | |
| 1878 | -These options allow pages to be selected from one or more PDF files.\n\ | |
| 1879 | -Whatever file is given as the primary input file is used as the\n\ | |
| 1880 | -starting point, but its pages are replaced with pages as specified.\n\ | |
| 1881 | -\n\ | |
| 1882 | ---keep-files-open=[yn]\n\ | |
| 1883 | ---pages file [ --password=password ] [ page-range ] ... --\n\ | |
| 1884 | -\n\ | |
| 1885 | -For each file that pages should be taken from, specify the file, a\n\ | |
| 1886 | -password needed to open the file (if any), and a page range. The\n\ | |
| 1887 | -password needs to be given only once per file. If any of the input\n\ | |
| 1888 | -files are the same as the primary input file or the file used to copy\n\ | |
| 1889 | -encryption parameters (if specified), you do not need to repeat the\n\ | |
| 1890 | -password here. The same file can be repeated multiple times. All\n\ | |
| 1891 | -non-page data (info, outlines, page numbers, etc. are taken from the\n\ | |
| 1892 | -primary input file. To discard this, use --empty as the primary\n\ | |
| 1893 | -input.\n\ | |
| 1894 | -\n\ | |
| 1895 | -By default, when more than 200 distinct files are specified, qpdf will\n\ | |
| 1896 | -close each file when not being referenced. With 200 files or fewer, all\n\ | |
| 1897 | -files will be kept open at the same time. This behavior can be overridden\n\ | |
| 1898 | -by specifying --keep-files-open=[yn]. Closing and opening files can have\n\ | |
| 1899 | -very high overhead on certain file systems, especially networked file\n\ | |
| 1900 | -systems.\n\ | |
| 1901 | -\n\ | |
| 1902 | -The page range is a set of numbers separated by commas, ranges of\n\ | |
| 1903 | -numbers separated dashes, or combinations of those. The character\n\ | |
| 1904 | -\"z\" represents the last page. A number preceded by an \"r\" indicates\n\ | |
| 1905 | -to count from the end, so \"r3-r1\" would be the last three pages of the\n\ | |
| 1906 | -document. Pages can appear in any order. Ranges can appear with a\n\ | |
| 1907 | -high number followed by a low number, which causes the pages to appear in\n\ | |
| 1908 | -reverse. Repeating a number will cause an error, but the manual discusses\n\ | |
| 1909 | -a workaround should you really want to include the same page twice.\n\ | |
| 1910 | -\n\ | |
| 1911 | -If the page range is omitted, the range of 1-z is assumed. qpdf decides\n\ | |
| 1912 | -that the page range is omitted if the range argument is either -- or a\n\ | |
| 1913 | -valid file name and not a valid range.\n\ | |
| 1914 | -\n\ | |
| 1915 | -The usual behavior of --pages is to add all pages from the first file,\n\ | |
| 1916 | -then all pages from the second file, and so on. If the --collate option\n\ | |
| 1917 | -is specified, then pages are collated instead. In other words, qpdf takes\n\ | |
| 1918 | -the first page from the first file, the first page from the second file,\n\ | |
| 1919 | -and so on until it runs out of files; then it takes the second page from\n\ | |
| 1920 | -each file, etc. When a file runs out of pages, it is skipped until all\n\ | |
| 1921 | -specified pages are taken from all files.\n\ | |
| 1922 | -\n\ | |
| 1923 | -See the manual for examples and a discussion of additional subtleties.\n\ | |
| 1924 | -\n\ | |
| 1925 | -\n\ | |
| 1926 | -Advanced Parsing Options\n\ | |
| 1927 | --------------------------------\n\ | |
| 1928 | -\n\ | |
| 1929 | -These options control aspects of how qpdf reads PDF files. Mostly these are\n\ | |
| 1930 | -of use to people who are working with damaged files. There is little reason\n\ | |
| 1931 | -to use these options unless you are trying to solve specific problems.\n\ | |
| 1932 | -\n\ | |
| 1933 | ---suppress-recovery prevents qpdf from attempting to recover damaged files\n\ | |
| 1934 | ---ignore-xref-streams tells qpdf to ignore any cross-reference streams\n\ | |
| 1935 | -\n\ | |
| 1936 | -\n\ | |
| 1937 | -Advanced Transformation Options\n\ | |
| 1938 | --------------------------------\n\ | |
| 1939 | -\n\ | |
| 1940 | -These transformation options control fine points of how qpdf creates\n\ | |
| 1941 | -the output file. Mostly these are of use only to people who are very\n\ | |
| 1942 | -familiar with the PDF file format or who are PDF developers.\n\ | |
| 1943 | -\n\ | |
| 1944 | ---stream-data=option controls transformation of stream data (below)\n\ | |
| 1945 | ---compress-streams=[yn] controls whether to compress streams on output\n\ | |
| 1946 | ---decode-level=option controls how to filter streams from the input\n\ | |
| 1947 | ---normalize-content=[yn] enables or disables normalization of content streams\n\ | |
| 1948 | ---object-streams=mode controls handing of object streams\n\ | |
| 1949 | ---preserve-unreferenced preserve unreferenced objects\n\ | |
| 1950 | ---preserve-unreferenced-resources\n\ | |
| 1951 | - preserve unreferenced page resources\n\ | |
| 1952 | ---newline-before-endstream always put a newline before endstream\n\ | |
| 1953 | ---coalesce-contents force all pages' content to be a single stream\n\ | |
| 1954 | ---flatten-annotations=option\n\ | |
| 1955 | - incorporate rendering of annotations into page\n\ | |
| 1956 | - contents including those for interactive form\n\ | |
| 1957 | - fields; may also want --generate-appearances\n\ | |
| 1958 | ---generate-appearances generate appearance streams for form fields\n\ | |
| 1959 | ---optimize-images compress images with DCT (JPEG) when advantageous\n\ | |
| 1960 | ---oi-min-width=w do not optimize images whose width is below w\n\ | |
| 1961 | ---oi-min-height=h do not optimize images whose height is below h\n\ | |
| 1962 | ---oi-min-area=a do not optimize images whose pixel count is below a\n\ | |
| 1963 | ---qdf turns on \"QDF mode\" (below)\n\ | |
| 1964 | ---linearize-pass1=file write intermediate pass of linearized file\n\ | |
| 1965 | - for debugging\n\ | |
| 1966 | ---min-version=version sets the minimum PDF version of the output file\n\ | |
| 1967 | ---force-version=version forces this to be the PDF version of the output file\n\ | |
| 1968 | -\n\ | |
| 1969 | -Options for --flatten-annotations are all, print, or screen. If the option\n\ | |
| 1970 | -is print, only annotations marked as print are included. If the option is\n\ | |
| 1971 | -screen, options marked as \"no view\" are excluded. Otherwise, annotations\n\ | |
| 1972 | -are flattened regardless of the presence of print or NoView flags. It is\n\ | |
| 1973 | -common for PDF files to have a flag set that appearance streams need to be\n\ | |
| 1974 | -regenerated. This happens when someone changes a form value with software\n\ | |
| 1975 | -that does not know how to render the new value. qpdf will not flatten form\n\ | |
| 1976 | -fields in files like this. If you get this warning, you have two choices:\n\ | |
| 1977 | -either use qpdf's --generate-appearances flag to tell qpdf to go ahead and\n\ | |
| 1978 | -regenerate appearances, or use some other tool to generate the appearances.\n\ | |
| 1979 | -qpdf does a pretty good job with most forms when only ASCII characters are\n\ | |
| 1980 | -used in form field values, but if your form fields contain other\n\ | |
| 1981 | -characters, rich text, or are other than left justified, you will get\n\ | |
| 1982 | -better results first saving with other software.\n\ | |
| 1983 | -\n\ | |
| 1984 | -Version numbers may be expressed as major.minor.extension-level, so 1.7.3\n\ | |
| 1985 | -means PDF version 1.7 at extension level 3.\n\ | |
| 1986 | -\n\ | |
| 1987 | -Values for stream data options:\n\ | |
| 1988 | -\n\ | |
| 1989 | - compress recompress stream data when possible (default)\n\ | |
| 1990 | - preserve leave all stream data as is\n\ | |
| 1991 | - uncompress uncompress stream data when possible\n\ | |
| 1992 | -\n\ | |
| 1993 | -Values for object stream mode:\n\ | |
| 1994 | -\n\ | |
| 1995 | - preserve preserve original object streams (default)\n\ | |
| 1996 | - disable don't write any object streams\n\ | |
| 1997 | - generate use object streams wherever possible\n\ | |
| 1998 | -\n\ | |
| 1999 | -When --compress-streams=n is specified, this overrides the default behavior\n\ | |
| 2000 | -of qpdf, which is to attempt compress uncompressed streams. Setting\n\ | |
| 2001 | -stream data mode to uncompress or preserve has the same effect.\n\ | |
| 2002 | -\n\ | |
| 2003 | -The --decode-level parameter may be set to one of the following values:\n\ | |
| 2004 | - none do not decode streams\n\ | |
| 2005 | - generalized decode streams compressed with generalized filters\n\ | |
| 2006 | - including LZW, Flate, and the ASCII encoding filters.\n\ | |
| 2007 | - specialized additionally decode streams with non-lossy specialized\n\ | |
| 2008 | - filters including RunLength\n\ | |
| 2009 | - all additionally decode streams with lossy filters\n\ | |
| 2010 | - including DCT (JPEG)\n\ | |
| 2011 | -\n\ | |
| 2012 | -In qdf mode, by default, content normalization is turned on, and the\n\ | |
| 2013 | -stream data mode is set to uncompress.\n\ | |
| 2014 | -\n\ | |
| 2015 | -Setting the minimum PDF version of the output file may raise the version\n\ | |
| 2016 | -but will never lower it. Forcing the PDF version of the output file may\n\ | |
| 2017 | -set the PDF version to a lower value than actually allowed by the file's\n\ | |
| 2018 | -contents. You should only do this if you have no other possible way to\n\ | |
| 2019 | -open the file or if you know that the file definitely doesn't include\n\ | |
| 2020 | -features not supported later versions.\n\ | |
| 2021 | -\n\ | |
| 2022 | -Testing, Inspection, and Debugging Options\n\ | |
| 2023 | -------------------------------------------\n\ | |
| 2024 | -\n\ | |
| 2025 | -These options can be useful for digging into PDF files or for use in\n\ | |
| 2026 | -automated test suites for software that uses the qpdf library.\n\ | |
| 2027 | -\n\ | |
| 2028 | ---deterministic-id generate deterministic /ID\n\ | |
| 2029 | ---static-id generate static /ID: FOR TESTING ONLY!\n\ | |
| 2030 | ---static-aes-iv use a static initialization vector for AES-CBC\n\ | |
| 2031 | - This is option is not secure! FOR TESTING ONLY!\n\ | |
| 2032 | ---no-original-object-ids suppress original object ID comments in qdf mode\n\ | |
| 2033 | ---show-encryption quickly show encryption parameters\n\ | |
| 2034 | ---show-encryption-key when showing encryption, reveal the actual key\n\ | |
| 2035 | ---check-linearization check file integrity and linearization status\n\ | |
| 2036 | ---show-linearization check and show all linearization data\n\ | |
| 2037 | ---show-xref show the contents of the cross-reference table\n\ | |
| 2038 | ---show-object=trailer|obj[,gen]\n\ | |
| 2039 | - show the contents of the given object\n\ | |
| 2040 | - --raw-stream-data show raw stream data instead of object contents\n\ | |
| 2041 | - --filtered-stream-data show filtered stream data instead of object contents\n\ | |
| 2042 | ---show-npages print the number of pages in the file\n\ | |
| 2043 | ---show-pages shows the object/generation number for each page\n\ | |
| 2044 | - --with-images also shows the object IDs for images on each page\n\ | |
| 2045 | ---check check file structure + encryption, linearization\n\ | |
| 2046 | ---json generate a json representation of the file\n\ | |
| 2047 | ---json-help describe the format of the json representation\n\ | |
| 2048 | ---json-key=key repeatable; prune json structure to include only\n\ | |
| 2049 | - specified keys. If absent, all keys are shown\n\ | |
| 2050 | ---json-object=trailer|[obj,gen]\n\ | |
| 2051 | - repeatable; include only specified objects in the\n\ | |
| 2052 | - \"objects\" section of the json. If absent, all\n\ | |
| 2053 | - objects are shown\n\ | |
| 2054 | -\n\ | |
| 2055 | -The json representation generated by qpdf is designed to facilitate\n\ | |
| 2056 | -processing of qpdf from other programming languages that have a hard\n\ | |
| 2057 | -time calling C++ APIs. Run qpdf --json-help for details on the format.\n\ | |
| 2058 | -The manual has more in-depth information about the json representation\n\ | |
| 2059 | -and certain compatibility guarantees that qpdf provides.\n\ | |
| 2060 | -\n\ | |
| 2061 | -The --raw-stream-data and --filtered-stream-data options are ignored\n\ | |
| 2062 | -unless --show-object is given. Either of these options will cause the\n\ | |
| 2063 | -stream data to be written to standard output.\n\ | |
| 2064 | -\n\ | |
| 2065 | -If --filtered-stream-data is given and --normalize-content=y is also\n\ | |
| 2066 | -given, qpdf will attempt to normalize the stream data as if it is a\n\ | |
| 2067 | -page content stream. This attempt will be made even if it is not a\n\ | |
| 2068 | -page content stream, in which case it will produce unusable results.\n\ | |
| 2069 | -\n\ | |
| 2070 | -Ordinarily, qpdf exits with a status of 0 on success or a status of 2\n\ | |
| 2071 | -if any errors occurred. If there were warnings but not errors, qpdf\n\ | |
| 2072 | -exits with a status of 3. If warnings would have been issued but --no-warn\n\ | |
| 2073 | -was given, an exit status of 3 is still used.\n\ | |
| 2074 | -\n"; | |
| 2075 | - | |
| 2076 | 2071 | void usageExit(std::string const& msg) |
| 2077 | 2072 | { |
| 2078 | 2073 | std::cerr | ... | ... |