managen 33 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279
  1. #!/usr/bin/env perl
  2. #***************************************************************************
  3. # _ _ ____ _
  4. # Project ___| | | | _ \| |
  5. # / __| | | | |_) | |
  6. # | (__| |_| | _ <| |___
  7. # \___|\___/|_| \_\_____|
  8. #
  9. # Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
  10. #
  11. # This software is licensed as described in the file COPYING, which
  12. # you should have received as part of this distribution. The terms
  13. # are also available at https://curl.se/docs/copyright.html.
  14. #
  15. # You may opt to use, copy, modify, merge, publish, distribute and/or sell
  16. # copies of the Software, and permit persons to whom the Software is
  17. # furnished to do so, under the terms of the COPYING file.
  18. #
  19. # This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  20. # KIND, either express or implied.
  21. #
  22. # SPDX-License-Identifier: curl
  23. #
  24. ###########################################################################
  25. =begin comment
  26. This script generates the manpage.
  27. Example: managen <command> [files] > curl.1
  28. Dev notes:
  29. We open *input* files in :crlf translation (a no-op on many platforms) in
  30. case we have CRLF line endings in Windows but a perl that defaults to LF.
  31. Unfortunately it seems some perls like msysgit cannot handle a global input-only
  32. :crlf so it has to be specified on each file open for text input.
  33. =end comment
  34. =cut
  35. my %optshort;
  36. my %optlong;
  37. my %helplong;
  38. my %arglong;
  39. my %redirlong;
  40. my %protolong;
  41. my %catlong;
  42. use POSIX qw(strftime);
  43. my @ts;
  44. if (defined($ENV{SOURCE_DATE_EPOCH})) {
  45. @ts = gmtime($ENV{SOURCE_DATE_EPOCH});
  46. } else {
  47. @ts = localtime;
  48. }
  49. my $date = strftime "%Y-%m-%d", @ts;
  50. my $year = strftime "%Y", @ts;
  51. my $version = "unknown";
  52. my $globals;
  53. my $error = 0;
  54. my $indent = 4;
  55. # get the long name version, return the manpage string
  56. sub manpageify {
  57. my ($k)=@_;
  58. my $l;
  59. my $trail;
  60. # the matching pattern might include a trailing dot that cannot be part of
  61. # the option name
  62. if($k =~ s/\.$//) {
  63. # cut off trailing dot
  64. $trail = ".";
  65. }
  66. my $klong = $k;
  67. # quote "bare" minuses in the long name
  68. $klong =~ s/-/\\-/g;
  69. if($optlong{$k}) {
  70. # both short + long
  71. $l = "\\fI-".$optlong{$k}.", \\-\\-$klong\\fP$trail";
  72. }
  73. else {
  74. # only long
  75. $l = "\\fI\\-\\-$klong\\fP$trail";
  76. }
  77. return $l;
  78. }
  79. my $colwidth=79; # max number of columns
  80. sub prefixline {
  81. my ($num) = @_;
  82. print "\t" x ($num/8);
  83. print ' ' x ($num%8);
  84. }
  85. sub justline {
  86. my ($lvl, @line) = @_;
  87. my $w = -1;
  88. my $spaces = -1;
  89. my $width = $colwidth - ($lvl * $indent);
  90. for(@line) {
  91. $w += length($_);
  92. $w++;
  93. $spaces++;
  94. }
  95. my $inject = $width - $w;
  96. my $ratio = 0; # stay at zero if no spaces at all
  97. if($spaces) {
  98. $ratio = $inject / $spaces;
  99. }
  100. my $spare = 0;
  101. prefixline($lvl * $indent);
  102. my $prev;
  103. for(@line) {
  104. while($spare >= 0.90) {
  105. print " ";
  106. $spare--;
  107. }
  108. printf "%s%s", $prev?" ":"", $_;
  109. $prev = 1;
  110. $spare += $ratio;
  111. }
  112. print "\n";
  113. }
  114. sub lastline {
  115. my ($lvl, @line) = @_;
  116. $line[0] =~ s/^( +)//;
  117. prefixline($lvl * $indent + length($1));
  118. my $prev = 0;
  119. for(@line) {
  120. printf "%s%s", $prev?" ":"", $_;
  121. $prev = 1;
  122. }
  123. print "\n";
  124. }
  125. sub outputpara {
  126. my ($lvl, $f) = @_;
  127. $f =~ s/\n/ /g;
  128. my $w = 0;
  129. my @words = split(/ */, $f);
  130. my $width = $colwidth - ($lvl * $indent);
  131. my @line;
  132. for my $e (@words) {
  133. my $l = length($e);
  134. my $spaces = scalar(@line);
  135. if(($w + $l + $spaces) >= $width) {
  136. justline($lvl, @line);
  137. undef @line;
  138. $w = 0;
  139. }
  140. push @line, $e;
  141. $w += $l; # new width
  142. }
  143. if($w) {
  144. lastline($lvl, @line);
  145. print "\n";
  146. }
  147. }
  148. sub printdesc {
  149. my ($manpage, $baselvl, @desc) = @_;
  150. if($manpage) {
  151. for my $d (@desc) {
  152. print $d;
  153. }
  154. }
  155. else {
  156. my $p = -1;
  157. my $para;
  158. for my $l (@desc) {
  159. my $lvl;
  160. if($l !~ /^[\n\r]+/) {
  161. # get the indent level off the string
  162. $l =~ s/^\[([0-9q]*)\]//;
  163. $lvl = $1;
  164. }
  165. if(($p =~ /q/) && ($lvl !~ /q/)) {
  166. # the previous was quoted, this is not
  167. print "\n";
  168. }
  169. if($lvl != $p) {
  170. outputpara($baselvl + $p, $para);
  171. $para = "";
  172. }
  173. if($lvl =~ /q/) {
  174. # quoted, do not right-justify
  175. chomp $l;
  176. lastline($baselvl + $lvl + 1, $l);
  177. my $w = ($baselvl + $lvl + 1) * $indent + length($l);
  178. if ($w > $colwidth) {
  179. print STDERR "ERROR: $w columns is too long\n";
  180. print STDERR "$l\n";
  181. $error++;
  182. }
  183. }
  184. else {
  185. $para .= $l;
  186. }
  187. $p = $lvl;
  188. }
  189. outputpara($baselvl + $p, $para);
  190. }
  191. }
  192. sub seealso {
  193. my($standalone, $data)=@_;
  194. if($standalone) {
  195. return sprintf
  196. ".SH \"SEE ALSO\"\n$data\n";
  197. }
  198. else {
  199. return "See also $data. ";
  200. }
  201. }
  202. sub overrides {
  203. my ($standalone, $data)=@_;
  204. if($standalone) {
  205. return ".SH \"OVERRIDES\"\n$data\n";
  206. }
  207. else {
  208. return $data;
  209. }
  210. }
  211. sub protocols {
  212. my ($manpage, $standalone, $data)=@_;
  213. if($standalone) {
  214. return ".SH \"PROTOCOLS\"\n$data\n";
  215. }
  216. else {
  217. return "($data) " if($manpage);
  218. return "[1]($data) " if(!$manpage);
  219. }
  220. }
  221. sub too_old {
  222. my ($version)=@_;
  223. my $a = 999999;
  224. if($version =~ /^(\d+)\.(\d+)\.(\d+)/) {
  225. $a = $1 * 1000 + $2 * 10 + $3;
  226. }
  227. elsif($version =~ /^(\d+)\.(\d+)/) {
  228. $a = $1 * 1000 + $2 * 10;
  229. }
  230. if($a < 7600) {
  231. # we consider everything before 7.60.0 to be too old to mention
  232. # specific changes for
  233. return 1;
  234. }
  235. return 0;
  236. }
  237. sub added {
  238. my ($standalone, $data)=@_;
  239. if(too_old($data)) {
  240. # do not mention ancient additions
  241. return "";
  242. }
  243. if($standalone) {
  244. return ".SH \"ADDED\"\nAdded in curl version $data\n";
  245. }
  246. else {
  247. return "Added in $data. ";
  248. }
  249. }
  250. sub render {
  251. my ($manpage, $fh, $f, $line) = @_;
  252. my @desc;
  253. my $tablemode = 0;
  254. my $header = 0;
  255. # if $top is TRUE, it means a top-level page and not a command line option
  256. my $top = ($line == 1);
  257. my $quote;
  258. my $level;
  259. my $finalblank;
  260. $start = 0;
  261. while(<$fh>) {
  262. my $d = $_;
  263. $line++;
  264. $finalblank = ($d eq "\n");
  265. if($d =~ /^\.(SH|BR|IP|B)/) {
  266. print STDERR "$f:$line:1:ERROR: nroff instruction in input: \".$1\"\n";
  267. return 4;
  268. }
  269. if(/^ *<!--/) {
  270. # skip comments
  271. next;
  272. }
  273. if((!$start) && ($_ =~ /^[\r\n]*\z/)) {
  274. # skip leading blank lines
  275. next;
  276. }
  277. $start = 1;
  278. if(/^# (.*)/) {
  279. $header = 1;
  280. if($top != 1) {
  281. # ignored for command line options
  282. $blankline++;
  283. next;
  284. }
  285. push @desc, ".SH $1\n" if($manpage);
  286. push @desc, "[0]$1\n" if(!$manpage);
  287. next;
  288. }
  289. elsif(/^###/) {
  290. print STDERR "$f:$line:1:ERROR: ### header is not supported\n";
  291. exit 3;
  292. }
  293. elsif(/^## (.*)/) {
  294. my $word = $1;
  295. # if there are enclosing quotes, remove them first
  296. $word =~ s/[\"\'](.*)[\"\']\z/$1/;
  297. # remove backticks from headers
  298. $word =~ s/\`//g;
  299. # if there is a space, it needs quotes for manpage
  300. if(($word =~ / /) && $manpage) {
  301. $word = "\"$word\"";
  302. }
  303. $level = 1;
  304. if($top == 1) {
  305. push @desc, ".IP $word\n" if($manpage);
  306. push @desc, "\n" if(!$manpage);
  307. push @desc, "[1]$word\n" if(!$manpage);
  308. }
  309. else {
  310. if(!$tablemode) {
  311. push @desc, ".RS\n" if($manpage);
  312. $tablemode = 1;
  313. }
  314. push @desc, ".IP $word\n" if($manpage);
  315. push @desc, "\n" if(!$manpage);
  316. push @desc, "[1]$word\n" if(!$manpage);
  317. }
  318. $header = 1;
  319. next;
  320. }
  321. elsif(/^##/) {
  322. if($top == 1) {
  323. print STDERR "$f:$line:1:ERROR: ## empty header top-level mode\n";
  324. exit 3;
  325. }
  326. if($tablemode) {
  327. # end of table
  328. push @desc, ".RE\n.IP\n" if($manpage);
  329. $tablemode = 0;
  330. }
  331. $header = 1;
  332. next;
  333. }
  334. elsif(/^\.(IP|RS|RE)/) {
  335. my ($cmd) = ($1);
  336. print STDERR "$f:$line:1:ERROR: $cmd detected, use ##-style\n";
  337. return 3;
  338. }
  339. elsif(/^[ \t]*\n/) {
  340. # count and ignore blank lines
  341. $blankline++;
  342. next;
  343. }
  344. elsif($d =~ /^ (.*)/) {
  345. my $word = $1;
  346. if(!$quote && $manpage) {
  347. push @desc, "\n" if($blankline);
  348. push @desc, ".nf\n";
  349. $blankline = 0;
  350. }
  351. $quote = 1;
  352. $d = "$word\n";
  353. }
  354. elsif($quote && ($d !~ /^ (.*)/)) {
  355. # end of quote
  356. push @desc, ".fi\n" if($manpage);
  357. $quote = 0;
  358. }
  359. $d =~ s/`%DATE`/$date/g;
  360. $d =~ s/`%VERSION`/$version/g;
  361. $d =~ s/`%GLOBALS`/$globals/g;
  362. # convert backticks to double quotes
  363. $d =~ s/\`/\"/g;
  364. if($d =~ /\(added in(.*)/i) {
  365. if(length($1) < 2) {
  366. print STDERR "$f:$line:1:ERROR: broken up added-in line:\n";
  367. print STDERR "$f:$line:1:ERROR: $d";
  368. return 3;
  369. }
  370. }
  371. again:
  372. if($d =~ /\(Added in ([0-9.]+)\)/i) {
  373. my $ver = $1;
  374. if(too_old($ver)) {
  375. $d =~ s/ *\(Added in $ver\)//gi;
  376. goto again;
  377. }
  378. }
  379. if(!$quote) {
  380. if($d =~ /^(.*) /) {
  381. printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n",
  382. length($1);
  383. return 3;
  384. }
  385. elsif($d =~ /[^\\][\<\>]/) {
  386. print STDERR "$f:$line:1:WARN: un-escaped < or > used\n";
  387. return 3;
  388. }
  389. }
  390. # convert backslash-'<' or '> to just the second character
  391. $d =~ s/\\([><])/$1/g;
  392. # convert single backslash to double-backslash
  393. $d =~ s/\\/\\\\/g if($manpage);
  394. if($manpage) {
  395. if(!$quote && $d =~ /--/) {
  396. $d =~ s/--([a-z0-9.-]+)/manpageify($1)/ge;
  397. }
  398. # quote minuses in the output
  399. $d =~ s/([^\\])-/$1\\-/g;
  400. # replace single quotes
  401. $d =~ s/\'/\\(aq/g;
  402. # handle double quotes or periods first on the line
  403. $d =~ s/^([\.\"])/\\&$1/;
  404. # **bold**
  405. $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g;
  406. # *italics*
  407. $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g;
  408. }
  409. else {
  410. # **bold**
  411. $d =~ s/\*\*(\S.*?)\*\*/$1/g;
  412. # *italics*
  413. $d =~ s/\*(\S.*?)\*/$1/g;
  414. }
  415. # trim trailing spaces
  416. $d =~ s/[ \t]+\z//;
  417. push @desc, "\n" if($blankline && !$header);
  418. $blankline = 0;
  419. push @desc, $d if($manpage);
  420. my $qstr = $quote ? "q": "";
  421. push @desc, "[".(1 + $level)."$qstr]$d" if(!$manpage);
  422. $header = 0;
  423. }
  424. if($finalblank) {
  425. print STDERR "$f:$line:1:ERROR: trailing blank line\n";
  426. exit 3;
  427. }
  428. if($quote) {
  429. # don't leave the quote "hanging"
  430. push @desc, ".fi\n" if($manpage);
  431. }
  432. if($tablemode) {
  433. # end of table
  434. push @desc, ".RE\n.IP\n" if($manpage);
  435. }
  436. return @desc;
  437. }
  438. sub maybespace {
  439. my ($string) = @_;
  440. if(($string =~ /(.* )(.*)/) &&
  441. (length($2) <= 20)) {
  442. return $1;
  443. }
  444. if(($string =~ /(.*:)(.*)/) &&
  445. (length($2) <= 20)) {
  446. return $1;
  447. }
  448. return $string;
  449. }
  450. sub single {
  451. my ($dir, $manpage, $f, $standalone)=@_;
  452. my $fh;
  453. open($fh, "<:crlf", "$dir/$f") ||
  454. die "could not find $dir/$f";
  455. my $short;
  456. my $long;
  457. my $tags;
  458. my $added;
  459. my $protocols;
  460. my $arg;
  461. my $mutexed;
  462. my $requires;
  463. my $category;
  464. my @seealso;
  465. my $copyright;
  466. my $spdx;
  467. my @examples; # there can be more than one
  468. my $magic; # cmdline special option
  469. my $line;
  470. my $dline;
  471. my $multi;
  472. my $scope;
  473. my $experimental;
  474. my $start;
  475. my $list; # identifies the list, 1 example, 2 see-also
  476. while(<$fh>) {
  477. $line++;
  478. if(/^ *<!--/) {
  479. next;
  480. }
  481. if(!$start) {
  482. if(/^---/) {
  483. $start = 1;
  484. }
  485. next;
  486. }
  487. if(/^Short: *(.)/i) {
  488. $short=$1;
  489. }
  490. elsif(/^Long: *(.*)/i) {
  491. $long=$1;
  492. }
  493. elsif(/^Added: *(.*)/i) {
  494. $added=$1;
  495. }
  496. elsif(/^Tags: *(.*)/i) {
  497. $tags=$1;
  498. }
  499. elsif(/^Arg: *(.*)/i) {
  500. $arg=$1;
  501. }
  502. elsif(/^Magic: *(.*)/i) {
  503. $magic=$1;
  504. }
  505. elsif(/^Mutexed: *(.*)/i) {
  506. $mutexed=$1;
  507. }
  508. elsif(/^Protocols: *(.*)/i) {
  509. $protocols=$1;
  510. }
  511. elsif(/^See-also: +(.+)/i) {
  512. if($seealso) {
  513. print STDERR "ERROR: duplicated See-also in $f\n";
  514. return 1;
  515. }
  516. push @seealso, $1;
  517. }
  518. elsif(/^See-also:/i) {
  519. $list=2;
  520. }
  521. elsif(/^ *- (.*)/i && ($list == 2)) {
  522. push @seealso, $1;
  523. }
  524. elsif(/^Requires: *(.*)/i) {
  525. $requires=$1;
  526. }
  527. elsif(/^Category: *(.*)/i) {
  528. $category=$1;
  529. }
  530. elsif(/^Example: +(.+)/i) {
  531. push @examples, $1;
  532. }
  533. elsif(/^Example:/i) {
  534. # '1' is the example list
  535. $list = 1;
  536. }
  537. elsif(/^ *- (.*)/i && ($list == 1)) {
  538. push @examples, $1;
  539. }
  540. elsif(/^Multi: *(.*)/i) {
  541. $multi=$1;
  542. }
  543. elsif(/^Scope: *(.*)/i) {
  544. $scope=$1;
  545. }
  546. elsif(/^Experimental: yes/i) {
  547. $experimental=1;
  548. }
  549. elsif(/^C: (.*)/i) {
  550. $copyright=$1;
  551. }
  552. elsif(/^SPDX-License-Identifier: (.*)/i) {
  553. $spdx=$1;
  554. }
  555. elsif(/^Help: *(.*)/i) {
  556. ;
  557. }
  558. elsif(/^---/) {
  559. $start++;
  560. if(!$long) {
  561. print STDERR "ERROR: no 'Long:' in $f\n";
  562. return 1;
  563. }
  564. if(!$category) {
  565. print STDERR "ERROR: no 'Category:' in $f\n";
  566. return 2;
  567. }
  568. if(!$examples[0]) {
  569. print STDERR "$f:$line:1:ERROR: no 'Example:' present\n";
  570. return 2;
  571. }
  572. if(!$added) {
  573. print STDERR "$f:$line:1:ERROR: no 'Added:' version present\n";
  574. return 2;
  575. }
  576. if(!$seealso[0]) {
  577. print STDERR "$f:$line:1:ERROR: no 'See-also:' field present\n";
  578. return 2;
  579. }
  580. if(!$copyright) {
  581. print STDERR "$f:$line:1:ERROR: no 'C:' field present\n";
  582. return 2;
  583. }
  584. if(!$spdx) {
  585. print STDERR "$f:$line:1:ERROR: no 'SPDX-License-Identifier:' field present\n";
  586. return 2;
  587. }
  588. last;
  589. }
  590. else {
  591. chomp;
  592. print STDERR "$f:$line:1:WARN: unrecognized line in $f, ignoring:\n:'$_';"
  593. }
  594. }
  595. if($start < 2) {
  596. print STDERR "$f:1:1:ERROR: no proper meta-data header\n";
  597. return 2;
  598. }
  599. my @desc = render($manpage, $fh, $f, $line);
  600. close($fh);
  601. if($tablemode) {
  602. # end of table
  603. push @desc, ".RE\n.IP\n";
  604. }
  605. my $opt;
  606. if(defined($short) && $long) {
  607. $opt = "-$short, --$long";
  608. }
  609. elsif($short && !$long) {
  610. $opt = "-$short";
  611. }
  612. elsif($long && !$short) {
  613. $opt = "--$long";
  614. }
  615. if($arg) {
  616. $opt .= " $arg";
  617. }
  618. # quote "bare" minuses in opt
  619. $opt =~ s/-/\\-/g if($manpage);
  620. if($standalone) {
  621. print ".TH curl 1 \"30 Nov 2016\" \"curl 7.52.0\" \"curl manual\"\n";
  622. print ".SH OPTION\n";
  623. print "curl $opt\n";
  624. }
  625. elsif($manpage) {
  626. print ".IP \"$opt\"\n";
  627. }
  628. else {
  629. lastline(1, $opt);
  630. }
  631. my @leading;
  632. if($protocols) {
  633. push @leading, protocols($manpage, $standalone, $protocols);
  634. }
  635. if($standalone) {
  636. print ".SH DESCRIPTION\n";
  637. }
  638. if($experimental) {
  639. push @leading, "**WARNING**: this option is experimental. Do not use in production.\n\n";
  640. }
  641. my $pre = $manpage ? "\n": "[1]";
  642. if($scope) {
  643. if($category !~ /global/) {
  644. print STDERR "$f:$line:1:ERROR: global scope option does not have global category\n";
  645. return 2;
  646. }
  647. if($scope eq "global") {
  648. push @desc, "\n" if(!$manpage);
  649. push @desc, "${pre}This option is global and does not need to be specified for each use of --next.\n";
  650. }
  651. else {
  652. print STDERR "$f:$line:1:ERROR: unrecognized scope: '$scope'\n";
  653. return 2;
  654. }
  655. }
  656. my @extra;
  657. if($multi eq "single") {
  658. push @extra, "${pre}If --$long is provided several times, the last set ".
  659. "value is used.\n";
  660. }
  661. elsif($multi eq "append") {
  662. push @extra, "${pre}--$long can be used several times in a command line\n";
  663. }
  664. elsif($multi eq "boolean") {
  665. my $rev = "no-$long";
  666. # for options that start with "no-" the reverse is then without
  667. # the no- prefix
  668. if($long =~ /^no-/) {
  669. $rev = $long;
  670. $rev =~ s/^no-//;
  671. }
  672. my $dashes = $manpage ? "\\-\\-" : "--";
  673. push @extra,
  674. "${pre}Providing --$long multiple times has no extra effect.\n".
  675. "Disable it again with $dashes$rev.\n";
  676. }
  677. elsif($multi eq "mutex") {
  678. push @extra,
  679. "${pre}Providing --$long multiple times has no extra effect.\n";
  680. }
  681. elsif($multi eq "custom") {
  682. ; # left for the text to describe
  683. }
  684. elsif($multi eq "per-URL") {
  685. push @extra,
  686. "${pre}--$long is associated with a single URL. Use it once per URL ".
  687. "when you use several URLs in a command line.\n";
  688. }
  689. else {
  690. print STDERR "$f:$line:1:ERROR: unrecognized Multi: '$multi'\n";
  691. return 2;
  692. }
  693. printdesc($manpage, 2, (@leading, @desc, @extra));
  694. undef @desc;
  695. my @foot;
  696. my $mstr;
  697. my $and = 0;
  698. my $num = scalar(@seealso);
  699. if($num > 2) {
  700. # use commas up to this point
  701. $and = $num - 1;
  702. }
  703. my $i = 0;
  704. for my $k (@seealso) {
  705. if(!$helplong{$k}) {
  706. print STDERR "$f:$line:1:WARN: see-also a non-existing option: $k\n";
  707. }
  708. my $l = $manpage ? manpageify($k) : "--$k";
  709. my $sep = " and";
  710. if($and && ($i < $and)) {
  711. $sep = ",";
  712. }
  713. $mstr .= sprintf "%s$l", $mstr?"$sep ":"";
  714. $i++;
  715. }
  716. if($requires) {
  717. my $l = $manpage ? manpageify($long) : "--$long";
  718. push @foot, "$l requires that libcurl".
  719. " is built to support $requires.\n";
  720. }
  721. if($mutexed) {
  722. my @m=split(/ /, $mutexed);
  723. my $mstr;
  724. my $num = scalar(@m);
  725. my $count;
  726. for my $k (@m) {
  727. if(!$helplong{$k}) {
  728. print STDERR "WARN: $f mutexes a non-existing option: $k\n";
  729. }
  730. my $l = $manpage ? manpageify($k) : "--$k";
  731. my $sep = ", ";
  732. if($count == ($num -1)) {
  733. $sep = " and ";
  734. }
  735. $mstr .= sprintf "%s$l", $mstr?$sep:"";
  736. $count++;
  737. }
  738. push @foot, overrides($standalone,
  739. "This option is mutually exclusive with $mstr.\n");
  740. }
  741. if($examples[0]) {
  742. my $s ="";
  743. $s="s" if($examples[1]);
  744. if($manpage) {
  745. print "\nExample$s:\n";
  746. print ".nf\n";
  747. foreach my $e (@examples) {
  748. $e =~ s!\$URL!https://example.com!g;
  749. # convert single backslahes to doubles
  750. $e =~ s/\\/\\\\/g;
  751. print "curl $e\n";
  752. }
  753. print ".fi\n";
  754. }
  755. else {
  756. my @ex;
  757. push @ex, "[0q]Example$s:\n";
  758. #
  759. # long ASCII examples are wrapped. Preferably at the last space
  760. # before the margin. Or at a colon. Otherwise it just cuts at the
  761. # exact boundary.
  762. #
  763. foreach my $e (@examples) {
  764. $e =~ s!\$URL!https://example.com!g;
  765. my $maxwidth = 60; # plus the " curl " 18 col prefix
  766. if(length($e) > $maxwidth) {
  767. # a long example, shorten it
  768. my $p = substr($e, 0, $maxwidth);
  769. $p = maybespace($p);
  770. push @ex, "[0q] curl ".$p."\\";
  771. $e = substr($e, length($p));
  772. do {
  773. my $r = substr($e, 0, $maxwidth);
  774. if(length($e) > $maxwidth) {
  775. $r = maybespace($r);
  776. }
  777. my $slash ="";
  778. $e = substr($e, length($r));
  779. if(length($e) > 0) {
  780. $slash = "\\";
  781. }
  782. push @ex, "[0q] $r$slash" if($r);
  783. } while(length($e));
  784. }
  785. else {
  786. push @ex, "[0q] curl $e\n";
  787. }
  788. }
  789. printdesc($manpage, 2, @ex);
  790. }
  791. }
  792. if($added) {
  793. push @foot, added($standalone, $added);
  794. }
  795. push @foot, seealso($standalone, $mstr);
  796. print "\n";
  797. my $f = join("", @foot);
  798. if($manpage) {
  799. $f =~ s/ +\z//; # remove trailing space
  800. print "$f\n";
  801. }
  802. else {
  803. printdesc($manpage, 2, "[1]$f");
  804. }
  805. return 0;
  806. }
  807. sub getshortlong {
  808. my ($dir, $f)=@_;
  809. $f =~ s/^.*\///;
  810. open(F, "<:crlf", "$dir/$f") ||
  811. die "could not find $dir/$f";
  812. my $short;
  813. my $long;
  814. my $help;
  815. my $arg;
  816. my $protocols;
  817. my $category;
  818. my $start = 0;
  819. my $line = 0;
  820. while(<F>) {
  821. $line++;
  822. if(!$start) {
  823. if(/^---/) {
  824. $start = 1;
  825. }
  826. next;
  827. }
  828. if(/^Short: (.)/i) {
  829. $short=$1;
  830. }
  831. elsif(/^Long: (.*)/i) {
  832. $long=$1;
  833. }
  834. elsif(/^Help: (.*)/i) {
  835. $help=$1;
  836. my $len = length($help);
  837. if($len >= 49) {
  838. printf STDERR "$f:$line:1:WARN: oversized help text: %d characters\n",
  839. $len;
  840. }
  841. }
  842. elsif(/^Arg: (.*)/i) {
  843. $arg=$1;
  844. }
  845. elsif(/^Protocols: (.*)/i) {
  846. $protocols=$1;
  847. }
  848. elsif(/^Category: (.*)/i) {
  849. $category=$1;
  850. }
  851. elsif(/^---/) {
  852. last;
  853. }
  854. }
  855. close(F);
  856. if($short) {
  857. $optshort{$short}=$long;
  858. }
  859. if($long) {
  860. $optlong{$long}=$short;
  861. $helplong{$long}=$help;
  862. $arglong{$long}=$arg;
  863. $protolong{$long}=$protocols;
  864. $catlong{$long}=$category;
  865. }
  866. }
  867. sub indexoptions {
  868. my ($dir, @files) = @_;
  869. foreach my $f (@files) {
  870. getshortlong($dir, $f);
  871. }
  872. }
  873. sub header {
  874. my ($dir, $manpage, $f)=@_;
  875. my $fh;
  876. open($fh, "<:crlf", "$dir/$f") ||
  877. die "could not find $dir/$f";
  878. my @d = render($manpage, $fh, $f, 1);
  879. close($fh);
  880. printdesc($manpage, 0, @d);
  881. }
  882. sub sourcecategories {
  883. my ($dir) = @_;
  884. my %cats;
  885. open(H, "<$dir/../../src/tool_help.h") ||
  886. die "can't find the header file";
  887. while(<H>) {
  888. if(/^\#define CURLHELP_([A-Z0-9]*)/) {
  889. $cats{lc($1)}++;
  890. }
  891. }
  892. close(H);
  893. return %cats;
  894. }
  895. sub listhelp {
  896. my ($dir) = @_;
  897. my %cats = sourcecategories($dir);
  898. print <<HEAD
  899. /***************************************************************************
  900. * _ _ ____ _
  901. * Project ___| | | | _ \\| |
  902. * / __| | | | |_) | |
  903. * | (__| |_| | _ <| |___
  904. * \\___|\\___/|_| \\_\\_____|
  905. *
  906. * Copyright (C) Daniel Stenberg, <daniel\@haxx.se>, et al.
  907. *
  908. * This software is licensed as described in the file COPYING, which
  909. * you should have received as part of this distribution. The terms
  910. * are also available at https://curl.se/docs/copyright.html.
  911. *
  912. * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  913. * copies of the Software, and permit persons to whom the Software is
  914. * furnished to do so, under the terms of the COPYING file.
  915. *
  916. * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  917. * KIND, either express or implied.
  918. *
  919. * SPDX-License-Identifier: curl
  920. *
  921. ***************************************************************************/
  922. #include "tool_setup.h"
  923. #include "tool_help.h"
  924. /*
  925. * DO NOT edit tool_listhelp.c manually.
  926. * This source file is generated with the following command in an autotools
  927. * build:
  928. *
  929. * "make listhelp"
  930. */
  931. const struct helptxt helptext[] = {
  932. HEAD
  933. ;
  934. foreach my $f (sort keys %helplong) {
  935. my $long = $f;
  936. my $short = $optlong{$long};
  937. my @categories = split ' ', $catlong{$long};
  938. my $bitmask = ' ';
  939. my $opt;
  940. if(defined($short) && $long) {
  941. $opt = "-$short, --$long";
  942. }
  943. elsif($long && !$short) {
  944. $opt = " --$long";
  945. }
  946. for my $i (0 .. $#categories) {
  947. if(!$cats{ $categories[$i] }) {
  948. printf STDERR "$f.md:ERROR: Unknown category '%s'\n",
  949. $categories[$i];
  950. exit 3;
  951. }
  952. $bitmask .= 'CURLHELP_' . uc $categories[$i];
  953. # If not last element, append |
  954. if($i < $#categories) {
  955. $bitmask .= ' | ';
  956. }
  957. }
  958. $bitmask =~ s/(?=.{76}).{1,76}\|/$&\n /g;
  959. my $arg = $arglong{$long};
  960. if($arg) {
  961. $opt .= " $arg";
  962. }
  963. my $desc = $helplong{$f};
  964. $desc =~ s/\"/\\\"/g; # escape double quotes
  965. my $line = sprintf " {\"%s\",\n \"%s\",\n %s},\n", $opt, $desc, $bitmask;
  966. if(length($opt) > 78) {
  967. print STDERR "WARN: the --$long name is too long\n";
  968. }
  969. elsif(length($desc) > 78) {
  970. print STDERR "WARN: the --$long description is too long\n";
  971. }
  972. print $line;
  973. }
  974. print <<FOOT
  975. { NULL, NULL, 0 }
  976. };
  977. FOOT
  978. ;
  979. }
  980. sub listcats {
  981. my %allcats;
  982. foreach my $f (sort keys %helplong) {
  983. my @categories = split ' ', $catlong{$f};
  984. foreach (@categories) {
  985. $allcats{$_} = undef;
  986. }
  987. }
  988. my @categories;
  989. foreach my $key (keys %allcats) {
  990. push @categories, $key;
  991. }
  992. @categories = sort @categories;
  993. for my $i (0..$#categories) {
  994. printf("#define CURLHELP_%-10s (%s)\n",
  995. uc($categories[$i]), "1u << ${i}u");
  996. }
  997. }
  998. sub listglobals {
  999. my ($dir, @files) = @_;
  1000. my @globalopts;
  1001. # Find all global options and output them
  1002. foreach my $f (sort @files) {
  1003. open(F, "<:crlf", "$dir/$f") ||
  1004. die "could not read $dir/$f";
  1005. my $long;
  1006. my $start = 0;
  1007. while(<F>) {
  1008. if(/^---/) {
  1009. if(!$start) {
  1010. $start = 1;
  1011. next;
  1012. }
  1013. else {
  1014. last;
  1015. }
  1016. }
  1017. if(/^Long: *(.*)/i) {
  1018. $long=$1;
  1019. }
  1020. elsif(/^Scope: global/i) {
  1021. push @globalopts, $long;
  1022. last;
  1023. }
  1024. }
  1025. close(F);
  1026. }
  1027. return $ret if($ret);
  1028. for my $e (0 .. $#globalopts) {
  1029. $globals .= sprintf "%s--%s", $e?($globalopts[$e+1] ? ", " : " and "):"",
  1030. $globalopts[$e],;
  1031. }
  1032. }
  1033. sub noext {
  1034. my $in = $_[0];
  1035. $in =~ s/\.md//;
  1036. return $in;
  1037. }
  1038. sub sortnames {
  1039. return noext($a) cmp noext($b);
  1040. }
  1041. sub mainpage {
  1042. my ($dir, $manpage, @files) = @_;
  1043. # $manpage is 1 for nroff, 0 for ASCII
  1044. my $ret;
  1045. my $fh;
  1046. open($fh, "<:crlf", "$dir/mainpage.idx") ||
  1047. die "no $dir/mainpage.idx file";
  1048. print <<HEADER
  1049. .\\" **************************************************************************
  1050. .\\" * _ _ ____ _
  1051. .\\" * Project ___| | | | _ \\| |
  1052. .\\" * / __| | | | |_) | |
  1053. .\\" * | (__| |_| | _ <| |___
  1054. .\\" * \\___|\\___/|_| \\_\\_____|
  1055. .\\" *
  1056. .\\" * Copyright (C) Daniel Stenberg, <daniel\@haxx.se>, et al.
  1057. .\\" *
  1058. .\\" * This software is licensed as described in the file COPYING, which
  1059. .\\" * you should have received as part of this distribution. The terms
  1060. .\\" * are also available at https://curl.se/docs/copyright.html.
  1061. .\\" *
  1062. .\\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  1063. .\\" * copies of the Software, and permit persons to whom the Software is
  1064. .\\" * furnished to do so, under the terms of the COPYING file.
  1065. .\\" *
  1066. .\\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  1067. .\\" * KIND, either express or implied.
  1068. .\\" *
  1069. .\\" * SPDX-License-Identifier: curl
  1070. .\\" *
  1071. .\\" **************************************************************************
  1072. .\\"
  1073. .\\" DO NOT EDIT. Generated by the curl project managen manpage generator.
  1074. .\\"
  1075. .TH curl 1 "$date" "curl $version" "curl Manual"
  1076. HEADER
  1077. if ($manpage);
  1078. while(<$fh>) {
  1079. my $f = $_;
  1080. chomp $f;
  1081. if($f =~ /^#/) {
  1082. # standard comment
  1083. next;
  1084. }
  1085. if(/^%options/) {
  1086. # output docs for all options
  1087. foreach my $f (sort sortnames @files) {
  1088. $ret += single($dir, $manpage, $f, 0);
  1089. }
  1090. }
  1091. else {
  1092. # render the file
  1093. header($dir, $manpage, $f);
  1094. }
  1095. }
  1096. close($fh);
  1097. exit $ret if($ret);
  1098. }
  1099. sub showonly {
  1100. my ($f) = @_;
  1101. if(single($f, 1)) {
  1102. print STDERR "$f: failed\n";
  1103. }
  1104. }
  1105. sub showprotocols {
  1106. my %prots;
  1107. foreach my $f (keys %optlong) {
  1108. my @p = split(/ /, $protolong{$f});
  1109. for my $p (@p) {
  1110. $prots{$p}++;
  1111. }
  1112. }
  1113. for(sort keys %prots) {
  1114. printf "$_ (%d options)\n", $prots{$_};
  1115. }
  1116. }
  1117. sub getargs {
  1118. my ($dir, $f, @s) = @_;
  1119. if($f eq "mainpage") {
  1120. listglobals($dir, @s);
  1121. mainpage($dir, 1, @s);
  1122. return;
  1123. }
  1124. elsif($f eq "ascii") {
  1125. listglobals($dir, @s);
  1126. mainpage($dir, 0, @s);
  1127. return;
  1128. }
  1129. elsif($f eq "listhelp") {
  1130. listhelp($dir);
  1131. return;
  1132. }
  1133. elsif($f eq "single") {
  1134. showonly($s[0]);
  1135. return;
  1136. }
  1137. elsif($f eq "protos") {
  1138. showprotocols();
  1139. return;
  1140. }
  1141. elsif($f eq "listcats") {
  1142. listcats();
  1143. return;
  1144. }
  1145. print "Usage: managen ".
  1146. "[-d dir] <mainpage/ascii/listhelp/single FILE/protos/listcats> [files]\n";
  1147. }
  1148. #------------------------------------------------------------------------
  1149. my $dir = ".";
  1150. my $include = "../../include";
  1151. my $cmd = shift @ARGV;
  1152. check:
  1153. if($cmd eq "-d") {
  1154. # specifies source directory
  1155. $dir = shift @ARGV;
  1156. $cmd = shift @ARGV;
  1157. goto check;
  1158. }
  1159. elsif($cmd eq "-I") {
  1160. # include path root
  1161. $include = shift @ARGV;
  1162. $cmd = shift @ARGV;
  1163. goto check;
  1164. }
  1165. elsif($cmd eq "-c") {
  1166. # Column width
  1167. $colwidth = 0 + shift @ARGV;
  1168. $cmd = shift @ARGV;
  1169. goto check;
  1170. }
  1171. my @files = @ARGV; # the rest are the files
  1172. # can be overridden for releases
  1173. if($ENV{'CURL_MAKETGZ_VERSION'}) {
  1174. $version = $ENV{'CURL_MAKETGZ_VERSION'};
  1175. }
  1176. else {
  1177. open(INC, "<$include/curl/curlver.h");
  1178. while(<INC>) {
  1179. if($_ =~ /^#define LIBCURL_VERSION \"([0-9.]*)/) {
  1180. $version = $1;
  1181. last;
  1182. }
  1183. }
  1184. close(INC);
  1185. }
  1186. # learn all existing options
  1187. indexoptions($dir, @files);
  1188. getargs($dir, $cmd, @files);
  1189. exit $error;