Mercurial > octave
annotate scripts/mkdoc.pl @ 23220:092078913d54
maint: Merge stable to default.
author | John W. Eaton <jwe@octave.org> |
---|---|
date | Wed, 22 Feb 2017 12:58:07 -0500 |
parents | 23847979b91e 3ac9f9ecfae5 |
children | 675ad11b5c05 |
rev | line source |
---|---|
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
1 #! /usr/bin/perl |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
2 use utf8; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
3 |
23219
3ac9f9ecfae5
maint: Update copyright dates.
John W. Eaton <jwe@octave.org>
parents:
22334
diff
changeset
|
4 # Copyright (C) 2012-2017 Rik Wehbring |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
5 # |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
6 # This file is part of Octave. |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
7 # |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
8 # Octave is free software; you can redistribute it and/or modify it |
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22334
diff
changeset
|
9 # under the terms of the GNU General Public License as published by |
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22334
diff
changeset
|
10 # the Free Software Foundation; either version 3 of the License, or |
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22334
diff
changeset
|
11 # (at your option) any later version. |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
12 # |
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22334
diff
changeset
|
13 # Octave is distributed in the hope that it will be useful, but |
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22334
diff
changeset
|
14 # WITHOUT ANY WARRANTY; without even the implied warranty of |
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22334
diff
changeset
|
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22334
diff
changeset
|
16 # GNU General Public License for more details. |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
17 # |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
18 # You should have received a copy of the GNU General Public License |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
19 # along with Octave; see the file COPYING. If not, see |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
20 # <http://www.gnu.org/licenses/>. |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
21 |
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
22 use strict; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
23 use warnings; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
24 use File::Spec; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
25 use Cwd; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
26 |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
27 ## Expecting arguments in this order: |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
28 ## |
21959
627f582edbe3
extract documentation from .in.m files instead of generated .m files
John W. Eaton <jwe@octave.org>
parents:
19697
diff
changeset
|
29 ## SRCDIR SRCDIR-FILES ... |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
30 |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
31 unless (@ARGV >= 2) { die "Usage: $0 srcdir m_filename1 ..." ; } |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
32 |
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
33 my $srcdir = shift (@ARGV); |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
34 |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
35 print <<__END_OF_MSG__; |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
36 ### DO NOT EDIT! |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
37 ### |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
38 ### This file is generated automatically from Octave source files. |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
39 ### Edit source files directly and run make to update this file. |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
40 |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
41 __END_OF_MSG__ |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
42 |
18943
714ce8ca71ea
mkdoc.pl: Tweaks to make code easier to understand for non-Perl experts.
Rik <rik@octave.org>
parents:
18940
diff
changeset
|
43 MFILE: foreach my $m_fname (@ARGV) |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
44 { |
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
45 my $full_fname = File::Spec->catfile ($srcdir, $m_fname); |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
46 my @paths = File::Spec->splitdir ($full_fname); |
18943
714ce8ca71ea
mkdoc.pl: Tweaks to make code easier to understand for non-Perl experts.
Rik <rik@octave.org>
parents:
18940
diff
changeset
|
47 if (@paths < 3 |
714ce8ca71ea
mkdoc.pl: Tweaks to make code easier to understand for non-Perl experts.
Rik <rik@octave.org>
parents:
18940
diff
changeset
|
48 || $paths[-2] eq "private" # skip private directories |
21959
627f582edbe3
extract documentation from .in.m files instead of generated .m files
John W. Eaton <jwe@octave.org>
parents:
19697
diff
changeset
|
49 || $paths[-1] !~ s/(\.in|)\.m$//i) # skip non m-files, and remove extension |
18943
714ce8ca71ea
mkdoc.pl: Tweaks to make code easier to understand for non-Perl experts.
Rik <rik@octave.org>
parents:
18940
diff
changeset
|
50 { next MFILE; } |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
51 |
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
52 ## @classes will have @class/method as their function name |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
53 my $fcn = $paths[-2] =~ m/^@/ ? File::Spec->catfile (@paths[-2, -1]) |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
54 : $paths[-1]; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
55 |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
56 my @help_txt = gethelp ($fcn, $full_fname); |
18943
714ce8ca71ea
mkdoc.pl: Tweaks to make code easier to understand for non-Perl experts.
Rik <rik@octave.org>
parents:
18940
diff
changeset
|
57 next MFILE unless @help_txt; |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
58 |
17256
ee1d19174316
doc: Use 0x1d as record separator for joint compatibility with Texinfo 4.x and 5.x.
Rik <rik@octave.org>
parents:
17242
diff
changeset
|
59 print "\x{1d}$fcn\n"; |
22334
fed9aa2ed01d
doc: Insert correct location of m-file into @c comment in .texi files.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
60 print "\@c $fcn $m_fname\n"; |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
61 |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
62 foreach $_ (@help_txt) |
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
63 { |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
64 my $in_example = (m/\s*\@example\b/ .. m/\s*\@end\s+example\b/); |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
65 s/^\s+\@/\@/ unless $in_example; |
18940
29fc1736a6be
scripts/mkdoc.pl: remove '@(end )?example' leading spaces from DOCSTRING.
Carnë Draug <carandraug@octave.org>
parents:
18939
diff
changeset
|
66 s/^\s+(\@(?:end)\s+(group|example))/$1/; |
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
67 print $_; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
68 } |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
69 } |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
70 |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
71 ################################################################################ |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
72 # Subroutines |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
73 ################################################################################ |
14644
f49e47ab83ca
maint: Rename mygethelp function to gethelp in scripts/mkdoc.pl
Rik <octave@nomad.inbox5.com>
parents:
14617
diff
changeset
|
74 sub gethelp |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
75 { |
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
76 my $fcn = shift; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
77 my $fname = shift; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
78 open (my $fh, "<", $fname) or return; |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
79 |
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
80 my @help_txt; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
81 while (my $line = <$fh>) |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
82 { |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
83 next if $line =~ m/^\s*$/; # skip empty lines |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
84 last if $line !~ m/^\s*(#|%)/; # out of here once code starts |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
85 |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
86 my $reading_block = sub {defined ($line = <$fh>) && $line !~ m/^\s*$/}; |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
87 |
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
88 ## Skip this block |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
89 if ($line =~ /(Copyright|Author)/) |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
90 { while (&$reading_block ()) {} } |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
91 else |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
92 { |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
93 do |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
94 { |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
95 $line =~ s/^\s*(%|#)+ ?//; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
96 push (@help_txt, $line); |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
97 } while (&$reading_block ()); |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
98 last; |
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
99 } |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
100 } |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
101 |
18939
b0960d4afe5f
scripts/mkdoc.pl: improve perl code portability.
Carnë Draug <carandraug@octave.org>
parents:
18938
diff
changeset
|
102 close ($fh); |
14617
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
103 return @help_txt; |
8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
Rik <octave@nomad.inbox5.com>
parents:
diff
changeset
|
104 } |