Mercurial > forge
changeset 95:32a07b48e913 octave-forge
Add new Perl script 'get_contents'. It finds CONTENTS files in the
directory tree, extracts the text from the files, and inserts the
text into the top-level README and the developer's guide html file.
The octave documentation can be kept up to date more easily this way.
| author | alnd |
|---|---|
| date | Wed, 02 Jan 2002 13:11:05 +0000 |
| parents | 203fc5aecba9 |
| children | 00daf5f848f3 |
| files | get_contents template.readme |
| diffstat | 2 files changed, 309 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/get_contents Wed Jan 02 13:11:05 2002 +0000 @@ -0,0 +1,171 @@ +#!/usr/bin/env perl +# +# Traverse the directory tree and look for files called 'CONTENTS'. +# Insert the text from these files into octave-forge documentation +# files such as the top-level README, and the developer's guide. +# Issues: +# - Entries in the README appear in the sort order of +# the directory names the CONTENTS files are in. This +# isn't necessarily the best sequence since some directories +# such as main/ should appear first. +# - At the moment the text in the CONTENTS files should be plain +# text. Planning to allow texinfo for layout control in .html +# files. +# +# Albert Danial Jan 2 2002 + +use strict; +use File::Find; + +my @files = (); # to contain relative path names of each CONTENTS file +find(\&wanted, "."); # start here & descend recursively; populate @files + +fill_README(@files); # creates 'README' from 'template.readme' +fill_developer_html(@files); # creates 'new_developer.html' from 'template.ndev' + +# # # # # # # + +sub fill_README { # {{{1 + my (@files, ) = @_; + my $template = "template.readme"; + my $RM = "README"; + if (!-r $template) { + warn "Unable to read the file '$template'; cannot make README\n"; + return; + } + open(IN, $template) or die "Unable to read $template: $!\n"; + my @template_data = <IN>; # slurp the entire file + close IN; + + my $added_contents = 0; + my $top_of_file = 1; + open(README, ">$RM") or die "Unable to write $RM: $!\n"; + foreach my $t (@template_data) { + if ($top_of_file) { # skip over warning lines in + next if $t =~ /^-> /; # template starting with '->' + $top_of_file = 0; + } elsif ($added_contents) { + print README $t; + next; + } elsif ($t =~ /^Project organization/) { + print README "$t\n"; + foreach (sort @files) { + open(CONTENTS, $_) or die "Cannot read $_: $!\n"; + my @c = <CONTENTS>; + close CONTENTS; + m{^(.*)/(.*?)$}; # match directory and file's basename + my $dir = $1; + my $file = $2; + $dir =~ s{^\./}{}; # strip leading ./ + print README "$dir/\n"; + foreach my $line (@c) { + print README "\t$line"; + } + print README "\n"; + } + $added_contents = 1; + } else { + print README $t; + } + } + close README; +} # 1}}} + +# # # # # # # + +sub fill_developer_html { # {{{1 + my (@files, ) = @_; + my $template = "admin/template.ndev"; + my $RM = "admin/new_developer.html"; + if (!-r $template) { + warn "Unable to read the file '$template'; cannot make README\n"; + return; + } + open(IN, $template) or die "Unable to read $template: $!\n"; + my @template_data = <IN>; # slurp the entire file + close IN; + + my $added_contents = 0; + my $top_of_file = 1; + open(README, ">$RM") or die "Unable to write $RM: $!\n"; + foreach my $t (@template_data) { + if ($top_of_file) { # skip over warning lines in + next if $t =~ /^-> /; # template starting with '->' + $top_of_file = 0; + } elsif ($added_contents) { + print README $t; + next; + } elsif ($t =~ /^>>>INSERT CONTENTS HERE<<</) { + foreach (sort @files) { + open(CONTENTS, $_) or die "Cannot read $_: $!\n"; + my @c = <CONTENTS>; + close CONTENTS; + text_bullet_list_to_HTML(\@c); + m{^(.*)/(.*?)$}; # match directory and file's basename + my $dir = $1; + my $file = $2; + $dir =~ s{^\./}{}; # strip leading ./ + print README "\t<li> <b><tt>$dir/</tt></b><br>\n"; + foreach my $line (@c) { + # use fixed font for words that end with / + # (ie, directory names). + $line =~ s{\s(\S+/)([.,\s])}{ <tt>$1</tt>$2}g; + print README "\t$line"; + } + print README "\n"; + } + $added_contents = 1; + } else { + print README $t; + } + } + close README; +} # 1}}} + +# # # # # # # + +sub text_bullet_list_to_HTML { # {{{1 + # Takes an array of plain text lines and embeds <ul>, <li>, and </ul> + # tags as appropriate to turn a text bullet list (denoted by *) into + # an html equivalent. + # Can only handle a single bullet list. + my ($ra_contents, ) = @_; + my $found_list = 0; + foreach my $l (@{$ra_contents}) { + if ($l =~ /^\s*\*/) { + $found_list = 1; + last; + } + } + return unless $found_list; # bail if no list found + + # find the first and last lines of the bullet list + my $start_line = 0; + for (my $i = 0; $i < scalar @{$ra_contents}; $i++) { + if ($ra_contents->[$i] =~ /^\s*\*/) { + $start_line = $i; + last; + } + } + my $end_line = 0; + for (my $i = scalar @{$ra_contents} - 1; $i >= 0; $i--) { + if ($ra_contents->[$i] =~ /^\s*\*/) { + $end_line = $i; + last; + } + } + + # finally, insert the HTML + for (my $i = 0; $i < scalar @{$ra_contents}; $i++) { + $ra_contents->[$i] =~ s{^(\s*)\*}{$1 <li>}; + $ra_contents->[$i] = "<ul> " . $ra_contents->[$i] if $i == $start_line; + $ra_contents->[$i] = $ra_contents->[$i] . "</ul>" if $i == $end_line; + } +} # 1}}} + +# # # # # # # + +sub wanted { # populates global array @files + return unless -f and /^CONTENTS$/; + push @files, "$File::Find::dir/$_"; +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/template.readme Wed Jan 02 13:11:05 2002 +0000 @@ -0,0 +1,138 @@ +-> Note: this is not the true README file. Create the correct top-level +-> README by running the Perl script 'get_contents'. get_contents +-> reads this file and the CONTENTS files in each subdirectory then +-> creates the README by populating the "Project organization" +-> section below with the information found in the CONTENTS files. +-> Albert Danial Jan 2 2002 + +The octave-forge project contains functions for Octave which are not in +the main distribution. While the main Octave distribution is +conservative about accepting new functions and changes, octave-forge is +very open. As a result, be prepared for some lower quality code and +more rapidly changing interfaces to the functions in octave-forge. + +The collection is in the public domain, but the individual functions +vary. See COPYING for details. See INSTALL for installation +instructions. + +===================================================================== +Project organization +====================================================================== +Package organization + +package/NOINSTALL + don't install this package; the user can rename or delete this + file if they want the package installed anyway. +package/*.m + m-files for the package; these will be installed in + site/mfiles/octave-forge/package +package/data/* + datafiles to be installed with the mfiles. You can accesses + them from your m-files with x = file_in_load_path("a"). +package/Makefile + Makefile with a default target to build anything that needs + building, and a "clean" target to remove anything that has been + built. See Makeconf.base for a list of predefined variables + and rules. + + Your Makefile could be as simple as: + + include ../../Makeconf + + all: f1.oct f2.oct + + clean: + $(RM) *.o *.oct octave-core core *~ + +package/configure.add +package/Makeconf.add + Additional configuration-time commands to run in order to + find all the components that your package requires. You + can look for anything you want in configure.add and note + what you need in Makeconf.add. The definitions in + Makeconf.add will be available when you include ../../Makeconf + into your Makefile. X11 is already included in Makeconf.base, + so you can just use $(X_LIBS) on your link line and $(X_CFLAGS) + on your compile line. +package/*.oct + oct-files built by Makefile. These will be installed all + together in site-oct-files/octave-forge. You may assume that + HAVE_OCTAVE_20 is defined for 2.0.x series mkoctfile, and + HAVE_OCTAVE_21 is defined for 2.1.x series mkoctfile. +package/bin/* + executable files built by Makefile. These will be + installed in Octave's EXEC_PATH, so they will be available + from Octave but not from the shell. + +Note: If you have files that you want installed in the standard +bindir/mandir/libdir/includedir, we need to consider automating +the procedure. At the time of writing extra/mex handles this +case with an install target in its Makefile, but special code is +put into extra/Makefile to trigger this. + +========================================================================== +Administration files + +autogen.sh + Generates ./configure and Makeconf.in + +configure.base +Makeconf.base + Basic configuration checks, such as locating the install paths, + and the associated variables to be put into Makeconf. Each + package can append checks by including configure.add in the + package directory. + +octinst.sh.in + Install program for packages, with pieces to be filed in by + ./configure + +install-sh + intall program to use if /usr/bin/install does not work + +COPYING + License for the collection, plus an out-of-date list of functions + in the collection and their licenses. + +COPYING.GPL + The text of the GPL license + +cvs-tree + Generate web listing of m-files in the tree + +README + This file + +TODO + Things that could/should be done + +INSTALL + Installation instructions + +Makefile + Top level makefile + +release.sh + Generates release tarball + +cvsdir.sh + Save/restore CVS adminstration files. You need this to install + directly from the CVS tree rather than an exported tarball. E.g., + $ cvsdir.sh save + $ make install + $ cvsdir.sh restore + +========================================================================== +Compatibility Issues + +Issue the following command: + $ grep -d skip "XXX COMPATIBILITY XXX" */* */*/* +for a list of compatibility issues in various functions. As of this +writing, mu2lin is a likely cause of problems when porting audio +packages. + + +========================================================================== +Paul Kienzle +pkienzle@users.sf.net +October 22, 2001