Mercurial > hg > octave-lyh
changeset 14617:8ffb01c3a27a
doc: Use Perl to create DOCSTRINGS in scripts directory.
* mkdoc.pl: Perl script that generates DOCSTRINGS file.
* Makefile.am: Use mkdoc.pl in build procedures.
* gethelp.cc: Remove C++ helper program for building DOCSTRINGS file.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Thu, 10 May 2012 16:58:41 -0700 |
parents | 13cc11418393 |
children | 36f451642f79 |
files | scripts/Makefile.am scripts/gethelp.cc scripts/mkdoc.pl |
diffstat | 3 files changed, 108 insertions(+), 168 deletions(-) [+] |
line wrap: on
line diff
--- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -325,21 +325,17 @@ : > time/$(octave_dirstamp) if AMCOND_BUILD_DOCS -## Program compiled only to help build documentation. No installation needed. -noinst_PROGRAMS = gethelp -gethelp_SOURCES = gethelp.cc - -.DOCSTRINGS: $(FCN_FILES) $(GEN_FCN_FILES) mkdoc $(gethelp_SOURCES) Makefile - @$(MAKE) $(AM_MAKEFLAGS) gethelp$(BUILD_EXEEXT) +.DOCSTRINGS: $(FCN_FILES) $(GEN_FCN_FILES) mkdoc.pl Makefile if [ "x$(srcdir)" != "x." ] && [ -f $(srcdir)/DOCSTRINGS ] && [ ! -f DOCSTRINGS ]; then \ cp $(srcdir)/DOCSTRINGS DOCSTRINGS; \ touch -r $(srcdir)/DOCSTRINGS DOCSTRINGS; \ fi @echo "creating .DOCSTRINGS from .m script files" - @$(srcdir)/mkdoc "$(srcdir)" $(FCN_FILES) -- $(GEN_FCN_FILES) > $@ + @$(PERL) $(srcdir)/mkdoc.pl "$(srcdir)" $(FCN_FILES) -- $(GEN_FCN_FILES) > $@ $(top_srcdir)/build-aux/move-if-change $@ DOCSTRINGS touch $@ + endif $(GEN_FCN_FILES) : %.m : %.in Makefile @@ -427,7 +423,7 @@ $(FCN_FILES_IN) \ $(GEN_FCN_FILES) \ DOCSTRINGS \ - mkdoc \ + mkdoc.pl \ mk-pkg-add DISTCLEANFILES = \
deleted file mode 100644 --- a/scripts/gethelp.cc +++ /dev/null @@ -1,160 +0,0 @@ -/* - -Copyright (C) 1999-2012 John W. Eaton - -This file is part of Octave. - -Octave is free software; you can redistribute it and/or modify it -under the terms of the GNU General Public License as published by the -Free Software Foundation; either version 3 of the License, or (at your -option) any later version. - -Octave is distributed in the hope that it will be useful, but WITHOUT -ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -for more details. - -You should have received a copy of the GNU General Public License -along with Octave; see the file COPYING. If not, see -<http://www.gnu.org/licenses/>. - -*/ - -#include <cstdio> - -#include <iostream> -#include <string> - -static bool -looks_like_octave_copyright (const std::string& s) -{ - // Perhaps someday we will want to do more here, so leave this as a - // separate function. - - return (s.substr (0, 9) == "Copyright" || s.substr (0, 6) == "Author"); -} - -// Eat whitespace and comments from FFILE, returning the text of the -// first block of comments that doesn't look like a copyright notice, - -static std::string -extract_help_text (void) -{ - std::string help_txt; - - bool first_comments_seen = false; - bool begin_comment = false; - bool have_help_text = false; - bool in_comment = false; - bool discard_space = true; - int c; - - while ((c = std::cin.get ()) != EOF) - { - if (begin_comment) - { - if (c == '%' || c == '#') - continue; - else if (discard_space && c == ' ') - { - discard_space = false; - continue; - } - else - begin_comment = false; - } - - if (in_comment) - { - if (! have_help_text) - { - first_comments_seen = true; - help_txt += static_cast<char> (c); - } - - if (c == '\n') - { - in_comment = false; - discard_space = true; - - if ((c = std::cin.get ()) != EOF) - { - if (c == '\n') - break; - } - else - break; - } - } - else - { - switch (c) - { - case ' ': - case '\t': - if (first_comments_seen) - have_help_text = true; - break; - - case '\n': - if (first_comments_seen) - have_help_text = true; - continue; - - case '%': - case '#': - begin_comment = true; - in_comment = true; - break; - - default: - goto done; - } - } - } - - done: - - if (! help_txt.empty ()) - { - if (looks_like_octave_copyright (help_txt)) - help_txt.resize (0); - - if (help_txt.empty ()) - help_txt = extract_help_text (); - } - - return help_txt; -} - -int -main (int argc, char **argv) -{ - std::string name; - std::string file_name; - - if (argc != 3) - { - std::cerr << "usage: gethelp name file-name\n"; - return 1; - } - else - { - name = argv[1]; - file_name = argv[2]; - } - - std::string help_text = extract_help_text (); - - if (! help_text.empty ()) - { - std::cout << "" << name << "\n" - << "@c " << name << " " << file_name << "\n" - << help_text; - - if (help_text[help_text.length () - 1] != '\n') - std::cout << "\n"; - } - - return 0; -}
new file mode 100755 --- /dev/null +++ b/scripts/mkdoc.pl @@ -0,0 +1,104 @@ +#! /usr/bin/perl -w +# +# Copyright (C) 2012 Rik Wehbring +# +# This file is part of Octave. +# +# Octave is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the +# Free Software Foundation; either version 3 of the License, or (at +# your option) any later version. +# +# Octave is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# +# You should have received a copy of the GNU General Public License +# along with Octave; see the file COPYING. If not, see +# <http://www.gnu.org/licenses/>. + +## Expecting arguments in this order: +## +## SRCDIR SRCDIR-FILES ... -- LOCAL-FILES ... + +unless (@ARGV >= 2) { die "Usage: $0 srcdir m_filename1 ..." ; } + +$srcdir = shift (@ARGV) . '/'; + +print <<__END_OF_MSG__; +### DO NOT EDIT! +### +### This file is generated automatically from Octave source files. +### Edit source files directly and run make to update this file. + +__END_OF_MSG__ + +MFILE: foreach $m_fname (@ARGV) +{ + if ($m_fname eq "--") + { + $srcdir = "./"; + next MFILE; + } + + $full_fname = $srcdir . $m_fname; + next MFILE unless ( $full_fname =~ m{(.*)/(@|)([^/]*)/(.*)\.m} ); + if ($2) { + $fcn = "$2$3/$4"; + } else { + $fcn = $4; + } + + @help_txt = mygethelp ($fcn, $full_fname); + next MFILE if ($help_txt[0] eq ""); + + print "$fcn\n"; + print "\@c $fcn scripts/$m_fname\n"; + + foreach $_ (@help_txt) + { + s/^\s+\@/\@/ unless $in_example; + s/^\s+\@group/\@group/; + s/^\s+\@end\s+group/\@end group/; + $in_example = (/\s*\@example\b/ .. /\s*\@end\s+example\b/); + print $_; + } +} + +################################################################################ +# Subroutines +################################################################################ +sub mygethelp +{ + ($fcn, $fname) = @_[0..1]; + open (FH, $fname) or return ""; + + do + { + @help_txt = (); + + ## Advance to non-blank line + while (defined ($_ = <FH>) and /^\s*$/) {;} + + if (! /^\s*(?:#|%)/ or eof (FH)) + { + ## No comment block found. Return empty string + close (FH); + return ""; + } + + ## Extract help text stopping when comment block ends + do + { + ## Remove comment characters at start of line + s/^\s*(?:#|%){1,2} ?//; + push (@help_txt, $_); + } until (! defined ($_ = <FH>) or ! /^\s*(?:#|%)/); + + } until ($help_txt[0] !~ /^(?:Copyright|Author)/); + + close (FH); + + return @help_txt; +}