diff -Nur --exclude=doc ruby-1.8.4/lib/rdoc/Makefile ../rdoc-f95-20060814/Makefile --- ruby-1.8.4/lib/rdoc/Makefile 1970-01-01 09:00:00.000000000 +0900 +++ ../rdoc-f95-20060814/Makefile 2006-07-08 13:29:24.000000000 +0900 @@ -0,0 +1,46 @@ +all: + +doc: + rdoc --op doc --title "RDoc-F95 Documentations" \ + --charset euc-jp --inline-source --line-numbers \ + --main README.ja \ + README README.ja README.org *.rb */*.rb */*/*.rb + +clean: clean-doc + test "`find . -name '*~'`" = "" || rm `find . -name '*~'` + +clean-doc: + test ! -d doc || rm -rf -v doc + +patch: + if [ ! -d patch_dir ] ; then \ + mkdir patch_dir ;\ + cd patch_dir ;\ + cvs -d :pserver:anonymous@cvs.ruby-lang.org:/src login ;\ + cvs -z4 -d :pserver:anonymous@cvs.ruby-lang.org:/src co ruby ;\ + fi + cd patch_dir/ruby ; cvs update + test -L patch_dir/ruby/lib/rdoc-f95 || \ + eval "cd patch_dir/ruby/lib ; ln -s ../../../ rdoc-f95" + cd patch_dir/ruby ; \ + diff \ + --exclude=rdoc \ + --exclude=parse_c.rb \ + --exclude=parse_rb.rb \ + --exclude=install.rb \ + --exclude=README* \ + --exclude=Makefile \ + --exclude=*~ \ + --exclude=CVS \ + --exclude=patch_dir \ + --exclude=rdoc-cvs.patch \ + --exclude=rdoc-cvs.patch.tmp \ + -Nur lib/rdoc/ lib/rdoc-f95/ > ../../rdoc-cvs.patch.tmp \ + || true + sed "s|^diff.*$$|diff -Nur lib/rdoc/ lib/rdoc-`date +%Y-%m-%d`/|" rdoc-cvs.patch.tmp > rdoc-cvs.patch + rm rdoc-cvs.patch.tmp + +clean-patch: + -rm -v rdoc-cvs.patch.tmp rdoc-cvs.patch + -rm -v -rf patch_dir/ruby + -rmdir patch_dir diff -Nur --exclude=doc ruby-1.8.4/lib/rdoc/README ../rdoc-f95-20060814/README --- ruby-1.8.4/lib/rdoc/README 2004-12-04 14:38:15.000000000 +0900 +++ ../rdoc-f95-20060814/README 2006-08-10 17:32:59.000000000 +0900 @@ -1,492 +1,297 @@ -= RDOC - Ruby Documentation System +({Japanese}[link:files/README_ja.html] | English) -This package contains Rdoc and SimpleMarkup. Rdoc is an application -that produces documentation for one or more Ruby source files. We work -similarly to JavaDoc, parsing the source, and extracting the -definition for classes, modules, and methods (along with includes and -requires). We associate with these optional documentation contained -in the immediately preceding comment block, and then render the result -using a pluggable output formatter. (Currently, HTML is the only -supported format. Markup is a library that converts plain text into -various output formats. The Markup library is used to interpret the -comment blocks that Rdoc uses to document methods, classes, and so on. - -This library contains two packages, rdoc itself and a text markup -library, 'markup'. - -== Roadmap - -* If you want to use Rdoc to create documentation for your Ruby source - files, read on. -* If you want to include extensions written in C, see rdoc/parsers/parse_c.rb. -* For information on the various markups available in comment - blocks, see markup/simple_markup.rb. -* If you want to drive Rdoc programatically, see RDoc::RDoc. -* If you want to use the library to format text blocks into HTML, - have a look at SM::SimpleMarkup. -* If you want to try writing your own HTML output template, see - RDoc::Page. - -== Summary - -Once installed, you can create documentation using the 'rdoc' command -(the command is 'rdoc.bat' under Windows) - - % rdoc [options] [names...] - -Type "rdoc --help" for an up-to-date option summary. - -A typical use might be to generate documentation for a package of Ruby -source (such as rdoc itself). - - % rdoc - -This command generates documentation for all the Ruby and C source -files in and below the current directory. These will be stored in a -documentation tree starting in the subdirectory 'doc'. - -You can make this slightly more useful for your readers by having the -index page contain the documentation for the primary file. In our -case, we could type - - % rdoc --main rdoc/rdoc.rb - -You'll find information on the various formatting tricks you can use -in comment blocks in the documentation this generates. - -RDoc uses file extensions to determine how to process each file. File -names ending .rb and .rbw are assumed to be Ruby -source. Files ending .c are parsed as C files. All other -files are assumed to contain just SimpleMarkup-style markup (with or -without leading '#' comment markers). If directory names are passed to -RDoc, they are scanned recursively for C and Ruby source files only. - -== Credits - -* The Ruby parser in rdoc/parse.rb is based heavily on the outstanding - work of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby - parser for irb and the rtags package. - -* Code to diagram classes and modules was written by Sergey A Yanovitsky - (Jah) of Enticla. - -* Charset patch from MoonWolf. - -* Rich Kilmer wrote the kilmer.rb output template. - -* Dan Brickley led the design of the RDF format. - -== License - -RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. It -is free software, and may be redistributed under the terms specified -in the README file of the Ruby distribution. - - ----- - -= Usage - -RDoc is invoked from the command line using: - - % rdoc [name...] - -Files are parsed, and the information they contain collected, before -any output is produced. This allows cross references between all files -to be resolved. If a name is a directory, it is traversed. If no -names are specified, all Ruby files in the current directory (and -subdirectories) are processed. - -Options are: - -[--accessor name[,name...]] - specifies the name(s) of additional methods that should be treated - as if they were attr_xxx methods. Specifying - "--accessor db_opt" means lines such as - - db_opt :name, :age - - will get parsed and displayed in the documentation. Each name may have an - optional "=flagtext" appended, in which case the given flagtext will appear - where (for example) the 'rw' appears for attr_accessor. - -[--all] - include protected and private methods in the output (by default - only public methods are included) - -[--charset _charset_] - Set the character set for the generated HTML. - -[--diagram] - include diagrams showing modules and classes. This is currently - an experimental feature, and may not be supported by all output - templates. You need dot V1.8.6 or later to use the --diagram - option correctly (http://www.research.att.com/sw/tools/graphviz/). - -[--exclude pattern] - exclude files and directories matching this pattern from processing - -[--extension new=old] - treat files ending .new as if they ended - .old. Saying '--extension cgi=rb' causes RDoc to treat .cgi - files as Ruby source. - -[fileboxes] - Classes are put in boxes which represents files, where these - classes reside. Classes shared between more than one file are - shown with list of files that sharing them. Silently discarded if - --diagram is not given Experimental. - -[--fmt _fmt_] - generate output in a particular format. - -[--help] - generate a usage summary. - -[--help-output] - explain the various output options. - -[--image-format gif/png/jpg/jpeg] - sets output image format for diagrams. Can be png, gif, jpeg, - jpg. If this option is omitted, png is used. Requires --diagram. - -[--include dir,...] - specify one or more directories to be searched when satisfying - :+include+: directives. Multiple --include options may be - given. The directory containing the file currently being processed - is always searched. - -[--inline-source] - By default, the source code of methods is shown in a popup. With - this option, it's displayed inline. - -[line-numbers] - include line numbers in the source code - -[--main _name_] - the class of module _name_ will appear on the index page. If you - want to set a particular file as a main page (a README, for - example) simply specifiy its name as the first on the command - line. - -[--merge] - when generating _ri_ output, if classes being processed already - exist in the destination directory, merge in the current details - rather than overwrite them. - -[--one-file] - place all the output into a single file - -[--op _dir_] - set the output directory to _dir_ (the default is the directory - "doc") - -[--op-name _name_] - set the name of the output. Has no effect for HTML. - "doc") - -[--opname _name_] - set the output name (has no effect for HTML). - -[--promiscuous] - If a module or class is defined in more than one source file, and - you click on a particular file's name in the top navigation pane, - RDoc will normally only show you the inner classes and modules of - that class that are defined in the particular file. Using this - option makes it show all classes and modules defined in the class, - regardless of the file they were defined in. - -[--quiet] - do not display progress messages - -[--ri, --ri-site, _and_ --ri-system] - generate output than can be read by the _ri_ command-line tool. - By default --ri places its output in ~/.rdoc, --ri-site in - $datadir/ri//site, and --ri-system in - $datadir/ri//system. All can be overridden with a subsequent - --op option. All default directories are in ri's default search - path. - -[--show-hash] - A name of the form #name in a comment is a possible hyperlink to - an instance method name. When displayed, the '#' is removed unless - this option is specified - -[--style stylesheet url] - specifies the URL of an external stylesheet to use (rather than - generating one of our own) - -[tab-width _n_] - set the width of tab characters (default 8) - -[--template name] - specify an alternate template to use when generating output (the - default is 'standard'). This template should be in a directory - accessible via $: as rdoc/generators/xxxx_template, where 'xxxx' - depends on the output formatter. - -[--version] - display RDoc's version - -[--webcvs _url_] - Specify a URL for linking to a web frontend to CVS. If the URL - contains a '\%s', the name of the current file will be - substituted; if the URL doesn't contain a '\%s', the filename will - be appended to it. - -= Example - -A typical small Ruby program commented using RDoc might be as follows. You -can see the formatted result in EXAMPLE.rb and Anagram. - - :include: EXAMPLE.rb - -= Markup - -Comment blocks can be written fairly naturally, either using '#' on -successive lines of the comment, or by including the comment in -an =begin/=end block. If you use the latter form, the =begin line -must be flagged with an RDoc tag: - - =begin rdoc - Documentation to - be processed by RDoc. - =end - -Paragraphs are lines that share the left margin. Text indented past -this margin are formatted verbatim. - -1. Lists are typed as indented paragraphs with: - * a '*' or '-' (for bullet lists) - * a digit followed by a period for - numbered lists - * an upper or lower case letter followed - by a period for alpha lists. - - For example, the input that produced the above paragraph looked like - 1. Lists are typed as indented - paragraphs with: - * a '*' or '-' (for bullet lists) - * a digit followed by a period for - numbered lists - * an upper or lower case letter followed - by a period for alpha lists. - -2. Labeled lists (sometimes called description - lists) are typed using square brackets for the label. - [cat] small domestic animal - [+cat+] command to copy standard input - -3. Labeled lists may also be produced by putting a double colon - after the label. This sets the result in tabular form, so the - descriptions all line up. This was used to create the 'author' - block at the bottom of this description. - cat:: small domestic animal - +cat+:: command to copy standard input - - For both kinds of labeled lists, if the body text starts on the same - line as the label, then the start of that text determines the block - indent for the rest of the body. The text may also start on the line - following the label, indented from the start of the label. This is - often preferable if the label is long. Both the following are - valid labeled list entries: - - --output name [, name]:: - specify the name of one or more output files. If multiple - files are present, the first is used as the index. - - --quiet::: do not output the names, sizes, byte counts, - index areas, or bit ratios of units as - they are processed. - -4. Headings are entered using equals signs - - = Level One Heading - == Level Two Heading - and so on - -5. Rules (horizontal lines) are entered using three or - more hyphens. - -6. Non-verbatim text can be marked up: - - _italic_:: \_word_ or \text - *bold*:: \*word* or \text - +typewriter+:: \+word+ or \text - - The first form only works around 'words', where a word is a - sequence of upper and lower case letters and underscores. Putting a - backslash before inline markup stops it being interpreted, which is - how I created the table above: - - _italic_:: \_word_ or \text - *bold*:: \*word* or \text - +typewriter+:: \+word+ or \text - -7. Names of classes, source files, and any method names - containing an underscore or preceded by a hash - character are automatically hyperlinked from - comment text to their description. - -8. Hyperlinks to the web starting http:, mailto:, ftp:, or www. are - recognized. An HTTP url that references an external image file is - converted into an inline . Hyperlinks starting 'link:' are - assumed to refer to local files whose path is relative to the --op - directory. - - Hyperlinks can also be of the form label[url], in which - case the label is used in the displayed text, and url is - used as the target. If label contains multiple words, - put it in braces: {multi word label}[url]. - -9. Method parameter lists are extracted and displayed with - the method description. If a method calls +yield+, then - the parameters passed to yield will also be displayed: - - def fred - ... - yield line, address - - This will get documented as - - fred() { |line, address| ... } - - You can override this using a comment containing - ':yields: ...' immediately after the method definition - - def fred # :yields: index, position - ... - yield line, address - - which will get documented as - - fred() { |index, position| ... } - - -10. ':yields:' is an example of a documentation modifier. These appear - immediately after the start of the document element they are modifying. - Other modifiers include - - [:nodoc:[all]] - don't include this element in the documentation. For classes - and modules, the methods, aliases, constants, and attributes - directly within the affected class or module will also be - omitted. By default, though, modules and classes within that - class of module _will_ be documented. This is turned off by - adding the +all+ modifier. - - module SM #:nodoc: - class Input - end - end - module Markup #:nodoc: all - class Output - end - end - - In the above code, only class SM::Input will be - documented. - - [:doc:] - force a method or attribute to be documented even if it - wouldn't otherwise be. Useful if, for example, you want to - include documentation of a particular private method. - - [:notnew:] - only applicable to the +initialize+ instance method. Normally - RDoc assumes that the documentation and parameters for - #initialize are actually for the ::new method, and so fakes - out a ::new for the class. THe :notnew: modifier stops - this. Remember that #initialize is protected, so you won't - see the documentation unless you use the -a command line - option. - - -11. RDoc stops processing comments if it finds a comment - line containing '#--'. This can be used to - separate external from internal comments, or - to stop a comment being associated with a method, - class, or module. Commenting can be turned back on with - a line that starts '#++'. - - # Extract the age and calculate the - # date-of-birth. - #-- - # FIXME: fails if the birthday falls on - # February 29th - #++ - # The DOB is returned as a Time object. - - def get_dob(person) - ... - -12. Comment blocks can contain other directives: - - [:section: title] - Starts a new section in the output. The title following - :section: is used as the section heading, and the - remainder of the comment containing the section is used as - introductory text. Subsequent methods, aliases, attributes, - and classes will be documented in this section. A :section: - comment block may have one or more lines before the :section: - directive. These will be removed, and any identical lines at - the end of the block are also removed. This allows you to add - visual cues such as - - # ---------------------------------------- - # :section: My Section - # This is the section that I wrote. - # See it glisten in the noon-day sun. - # ---------------------------------------- - - [call-seq:] - lines up to the next blank line in the comment are treated as - the method's calling sequence, overriding the - default parsing of method parameters and yield arguments. - - [:include:filename] - include the contents of the named file at this point. The - file will be searched for in the directories listed by - the --include option, or in the current - directory by default. The contents of the file will be - shifted to have the same indentation as the ':' at the - start of the :include: directive. - - [:title:text] - Sets the title for the document. Equivalent to the --title command - line parameter. (The command line parameter overrides any :title: - directive in the source). - - [:enddoc:] - Document nothing further at the current level. - - [:main:name] - Equivalent to the --main command line parameter. - - [:stopdoc: / :startdoc:] - Stop and start adding new documentation elements to the - current container. For example, if a class has a number of - constants that you don't want to document, put a - :stopdoc: before the first, and a - :startdoc: after the last. If you don't specifiy a - :startdoc: by the end of the container, disables - documentation for the entire class or module. - - ---- - -See also markup/simple_markup.rb. - -= Other stuff - -Author:: Dave Thomas -Requires:: Ruby 1.8.1 or later -License:: Copyright (c) 2001-2003 Dave Thomas. - Released under the same license as Ruby. - -== Warranty - -This software is provided "as is" and without any express or -implied warranties, including, without limitation, the implied -warranties of merchantibility and fitness for a particular -purpose. += Enhanced version of RDoc Fortran 90/95 parser (for GFD Dennou Club dcmodel project) + +Here is a patch file to improve +RDoc[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html] +analysis feature +for Fortran 90/95 source codes. +Patched package of RDoc source is also available. + +== Operation verification + +Operation of this package are verified with Ruby 1.8.2. + +== Download + +The latest version (Version $Name: rdoc-f95-20060814 $) + +* {Patch for Ruby 1.8.4}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95-patch_for_ruby1.8.4] + +* {TGZ file of RDoc resources to which above patch applied }[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95.tgz] + +* {Binary packages for Debian GNU/Linux}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/debian] + +Archives of old versions + +* {Patch files, TGZ packages, source code trees (only JAPANESE)}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/arch/SIGEN.htm] + +== Install + +=== How to apply the patch to original Ruby package + +To use the patch file, follow steps described below: + +* Download + ftp://ftp.ruby-lang.org/pub/ruby/ruby-1.8.4.tar.gz + from {Ruby Home Page}[http://www.ruby-lang.org/]. + +* Unpack the archive file as + + % tar xvfz ruby-1.8.4.tar.gz + +* Put the patch file (rdoc-f95-patch_for_ruby1.8.4) + on the directory where you executed tar command, + and apply the patch; + + % patch -p0 < rdoc-f95-patch_for_ruby1.8.4 + +* Install RDoc package as written in + {Site of the Ruby}[http://www.ruby-lang.org/]. + +=== How to install patched RDoc package + +To install RDoc package which is patched, +follow steps described below: + +* Download archive file rdoc-f95.tgz + +* Unpack: + + % tar xvfz rdoc-f95.tgz + +* Go into the Ruby source directory: + + % cd rdoc-f95 + +* Install the package: + + % ruby install.rb + +If rdoc is already installed, the original rdoc will be overritten. + +Use --help option to show options and the directory to which +rdoc is installed: + + % ruby install.rb --help + +=== How to use binary packages for Debian GNU/Linux + +Download a debian package, and install as follows. + + % dpkg -i rdoc-f95_20060809_i386.deb + +Original "rdoc" package is replaced with this "rdoc-f95" package. +If you add following URL to sources.list of APT, you can install +and update "rdoc-f95" package by APT commands. + + deb http://www.gfd-dennou.org/library/cc-env/Linux/debian-dennou stable/ + + +== Usage + +Set environment variable *PATH* so as to include +the directory where the execution program is installed, +and *RUBYLIB* so as to include the directory +where the libraries are installed. + +Move to a directory where your Fortran 90/95 files exist, +and execute the following command. HTML documents will be generated in +*doc* directory. + + % rdoc --ignore-case --inline-source + +Files ending .f90, .F90, .f95, .F95 +are parsed as Fortran 90/95 programs. +All Fortran 90/95 programs in subdirectories are parsed recursively. + +As well as original RDoc, files ending .rb and .rbw +are parsed as Ruby programs, files ending .c, .cc, +.cpp, .CC, .cxx are parsed as C programs. + +With --op option, +directory where HTML documents are generated can be changed. +--title option sets title of HTML documents. +When --all option is used, +private subroutines, functions etc. in +Fortran 90/95 programs are shown in HTML documents (for developers). +If files are specified as arguments (for example, +src/*.f90), the particular files are parsed. +An Example is the following. + + % rdoc --ignore-case --inline-source \ + --op rdoc --title "RDoc documentations" src/*.f90 test/*.f90 + +For more information, +see {README of original RDoc}[link:files/README_org.html]. + + +== Rules for RDoc Document + +Refer parsers/parse_f95.rb which +explains parsed information, way of looking at documents, +the format of comment blocks in Fortran 90/95 source code. +If you use "--mathml" option (see below), +refer Generators::TexParser, too. +For general information, see +{README of original RDoc}[link:files/README_org.html] . + +== Samples + +* {Code reference of data I/O library gt4f90io (only JAPANESE)}[http://www.gfd-dennou.org/library/gtool4/gt4f90io/gt4f90io_current/doc/develop_reference/] + +* {Code reference of planetary atmospheric general circulation model DCPAM (only JAPANESE)}[http://www.gfd-dennou.org/library/dcpam/dcpam3/dcpam3_current/doc/code_reference/htm] + +== Differences from original RDoc + +This patch is created for enhancing Fortran 90/95 parser of RDoc . +{Fortran 90/95 parse script parse_f95.rb}[http://www.ruby-lang.org/cgi-bin/cvsweb.cgi/ruby/lib/rdoc/parsers/parse_f95.rb] +is mainly modified, and other programs are also improved. + + +Original RDoc is developed by Dave Thomas, and now, +maintained by Ryan Davis. The RDoc is available from Ruby CVS +repository http://www.ruby-lang.org/ja/20020106.html . +For more information about RDoc, +see +{README of original RDoc}[link:files/README_org.html] . + +Differences with original are as follows. +Note that some differences were lost because +this patch (2005/12/17 version) was already taken into +original RDoc package. + +-- +#Enhancement of an analytical performance of Fortran 90/95 source codes :: +# See parsers/parse_f95.rb for details. + +#Modification of format of comment blocks :: +# See parsers/parse_f95.rb for details. +++ + +Addition of --ignore-case option :: + In the Fortran 90/95 Standard, + upper case letters are not distinguished from lower case letters, + although original RDoc produces case-dependently + cross-references of Class and Methods. + When this options is specified, + upper cases are not distinguished from lower cases. + +Cross-reference of file names :: + Cross-reference of file names is available as well as + modules, subroutines, and so on. + +Modification of --style option :: + Original rdoc can not treat relative path stylesheet. + Application of this patch modifies this function. + +Conversion of TeX formula into MathML :: + TeX formula can be converted into MathML. + MathML library for Ruby version 0.5 is needed. + This library is available from {Bottega of Hiraku (JAPANESE only)}[http://www.hinet.mydns.jp/~hiraku/]. + If you use this function, use --mathml option. + See Generators::TexParser about format. + + *** Caution *** + Documents generated with "--mathml" option are displayed correctly + with {Mozilla Firefox}[http://www.mozilla.or.jp/products/firefox/] + or Internet Explorer + (+ {MathPlayer}[http://www.dessci.com/en/products/mathplayer/]). + See {MathML Software - Browsers}[http://www.w3.org/Math/Software/mathml_software_cat_browsers.html] + about other browsers. + +Some formats of comments in HTML document are changed +because of improvement of analysis features. +See parsers/parse_f95.rb for details. + + +== Remarks in use + +Enhanced version of RDoc Fortran 90/95 parser +is being constructed on the premise of +the uses for educations and academic researches. For those uses, +the resources are permitted to use and modify without any +notification. +Licence of Enhanced version of RDoc Fortran 90/95 parser +conforms to that of original RDoc. +See {README of original RDoc}[link:files/README_org.html] . + +When you publish your scientific/technological works +using Enhanced version of RDoc Fortran 90/95 parser, +we will be very glad if you cite our resources +in the following way: + + Morikawa,Y., Ishiwatari,M., Horinouchi,T., Odaka,M., Hayashi,Y.-Y., + dcmodel: Numerical Model Porject, 2006: + Enhanced version of RDoc Fortran 90/95 parser, + http://www.gfd-dennou.org/library/dcmodel/, GFD Dennou Club. + +== Contact + +Please see end of +{dcmodel: GFD Dennou Club Numerical Model Porject}[http://www.gfd-dennou.org/library/dcmodel/index.htm.en] + + +== History + +==== 2006/08/14 + +* Package name is changed from "rdoc-dennou" to "rdoc-f95". +* Address is changed as + http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/ +* README and README.ja are modified. +* Conversion of TeX formula into MathML is enable. +* Modification of --style option. +* Main programs are added to 'Methods' too. +* The NAMELIST group names scattered in each file are collected on one page. +* Names of modules provided by F90 files are added to documents of the files + automatically. + + +==== 2006/02/24 + +* English version of README is created. + +==== 2006/01/18 +* Comment formats for arguments of subroutines and functions + are slightly modified. + + * A space is inserted below the argument described in HTML document. + +* Patched package is rebulid with + updated Ruby resources in CVS repository. + +==== 2005/12/28 +* Patch file for ruby 1.8.4 is released. + +==== 2005/12/17 + +* Some bugs are fixed. +* Parsing external subroutines specified interface are improved. +* Handling of Continuation lines are improved. + +==== 2005/12/13 + +* Remarks and Todo are added in parsers/parse_f95.rb +* Sample is added in README +* Parsing part of public, private statements + are improved. + +==== 2005/12/08 + +* "Remarks in use" and "Contact" are added in README . +* Address is changed as + http://www.gfd-dennou.org/library/dcmodel/rdoc-dennou/ + +==== 2005/11/28 + +* ":nodoc:" tag are available. +* Parsing "contains" in subroutines and functions are improved. +* Title is changed. +* Old version of the patches are placed in web page. + +==== 2005/11/17 + +* Improvement of analysis features, checking HTML documents + which are produced by RDoc. + release of preliminary version. diff -Nur --exclude=doc ruby-1.8.4/lib/rdoc/README.ja ../rdoc-f95-20060814/README.ja --- ruby-1.8.4/lib/rdoc/README.ja 1970-01-01 09:00:00.000000000 +0900 +++ ../rdoc-f95-20060814/README.ja 2006-08-10 17:32:59.000000000 +0900 @@ -0,0 +1,347 @@ +(Japanese | {English}[link:files/README.html]) + += RDoc Fortran 90/95 ソースコード解析機能強化版 (地球流体電脳倶楽部 dcmodel プロジェクト用) + +{RDoc - Ruby Documentation System}[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html] +の Fortran 90/95 ソースコード解析機能を強化するためのパッチを +配布しています. パッチを適用したパッケージも配布しています. + +== 動作確認 + +このパッケージは Ruby 1.8.2 での動作を確認しています. + +== ダウンロード + +最新版 (バージョン $Name: rdoc-f95-20060814 $) + +* {Ruby 1.8.4 用のパッチ}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95-patch_for_ruby1.8.4] + +* {rdoc-f95 tar.gz パッケージ (Ruby 1.8.4 の rdoc の部分を取り出し, 上記パッチを適用して tar ボールにしたもの)}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/rdoc-f95.tgz] + +* {Debian GNU/Linux 用バイナリパッケージ}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/debian] + + +過去のアーカイブ + +* {パッチ ・ TGZ パッケージ ・ ソースツリーのリスト}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/arch/SIGEN.htm] + +== インストール + +=== パッチファイルを利用する方法 + +パッチファイルを Ruby のオリジナル資源に適用する手順は +以下の通りです. + +* まず, {Ruby のホームページ}[http://www.ruby-lang.org/] から + ftp://ftp.ruby-lang.org/pub/ruby/ruby-1.8.4.tar.gz + をダウンロードしてください + +* 上記 TGZ ファイルを展開してください. + + % tar xvfz ruby-1.8.4.tar.gz + +* このコマンドを実行したディレクトリに上記のパッチファイル + rdoc-f95-patch_for_ruby1.8.4 を置き, 以下のコマンドでパッチを + 適用してください. + + % patch -p0 < rdoc-f95-patch_for_ruby1.8.4 + +* パッチを適用した後に, Ruby のインストール作業を行ってください. + Ruby のインストール方法は + {オブジェクト指向スクリプト言語 Ruby のホームページ}[http://www.ruby-lang.org/] + を参照してください. + +=== パッチが適用されたパッケージを利用する方法 + +パッチが適用された rdoc-f95.tgz パッケージを使用するには +以下のようにします. + +アーカイブファイル rdoc-f95.tgz をダウンロードした後に, +以下のように tar コマンドで展開後, +install.rb でインストールを行ってください. +既に rdoc がインストールされている場合, 上書きする可能性があります. + + % tar xvfz rdoc-f95.tgz + % cd rdoc-f95 + % ruby install.rb + +インストール先のディレクトリや, 変更のためのオプションに関しては, +以下のコマンドで知ることが出来ます. + + % ruby install.rb --help + +=== Debian GNU/Linux 用バイナリパッケージを利用する方法 + +debian パッケージをダウンロードし, 以下のようにインストールを +行ないます. + + % dpkg -i rdoc-f95_20060809_i386.deb + +オリジナルの rdoc パッケージが rdoc-f95 パッケージに置き換わります. +以下の URL を APT のソースリストに加えておくと, APT のコマンドで +rdoc-f95 パッケージのインストールや更新が可能になります. + + deb http://www.gfd-dennou.org/library/cc-env/Linux/debian-dennou stable/ + + +== RDoc の使用方法 + +実行プログラムがインストールされた場所を環境変数 *PATH* +に設定し, ライブラリがインストールされた場所を環境変数 *RUBYLIB* +に設定してください. + +Fortran 90/95 ファイルが置いてあるディレクトリまで移動し, 以下のコマンドを +実行してください. *doc* ディレクトリ以下にドキュメントが作成されます. + + % rdoc --ignore-case --charset euc-jp --inline-source + +拡張子が .f90, .F90, .f95, .F95 +であるファイルは Fortran 90/95 プログラムとして解析されます. +サブディレクトリ以下の全ての Fortran 90/95 プログラムも解析されます. + +なお, オリジナルの RDoc と同様, 拡張子が .rb, +.rbw であるファイルは Ruby プログラムとして, 拡張子が +.c, .cc, .cpp, .CC, .cxx +であるファイルは C プログラムとして解析されます. + +*doc* ディレクトリ以外に出力したい場合は, +--op オプションをつけてください. +タイトルは +--title オプションで変更できます. +また, デフォルトでは Fortran 90/95 の private 属性のサブルーチンや関数 +などはドキュメントに出力されませんが, --all オプションを +つけることで, 全てがドキュメントに出力されます. +--charsetオプションは, ドキュメントに反映されるコメントに +日本語など 2 バイト文字が含まれる場合に用います. +コメントの文字コードに合わせ, euc-jp, Shift_JIS, +iso-2022-jp などを指定してください. + +一部のファイルのみを +ドキュメント化したい場合は, 引数に src/*.f90 などと +ファイル名を明示的に指定してください. 以下の例参照. + + % rdoc --ignore-case --charset euc-jp --inline-source \ + --op rdoc --title "RDoc documentations" src/*.f90 test/*.f90 + +詳しいことは +{RDoc オリジナルの README}[link:files/README_org.html] +を参照ください. + + +== 書法 + +解析される情報やドキュメントの見方, コメント部の書き方に関しては, +parsers/parse_f95.rb を参照ください. --mathml オプション (下記参照) +を使用する場合には, Generators::TexParser も参照ください. +ただし, これらに記述されるのは Fortran 90/95 などに特有な部分なので, +一般的な部分に関しては +{RDoc オリジナルの README}[link:files/README_org.html] +を参照ください. +大林さんによる日本語訳が http://www.kmc.gr.jp/~ohai/rdoc.ja.html にあります. + +== サンプル + +* {データ I/O ライブラリ gt4f90io のコードリファレンス}[http://www.gfd-dennou.org/library/gtool4/gt4f90io/gt4f90io_current/doc/develop_reference/] + +* {惑星大気モデル DCPAM のコードリファレンス (製作中)}[http://www.gfd-dennou.org/library/dcpam/dcpam3/dcpam3_current/doc/code_reference/htm] + + +== オリジナルの RDoc との違い + +ここで配布するパッチは, RDoc の Fortran 90/95 ソースコードの +解析能力を大幅に向上させ, Fortran 90/95 プログラムから +自動生成されるドキュメントの情報量を充実させます. +主に改良されているのは, 元々の RDoc に付属される +{Fortran 90/95 解析プログラム parse_f95.rb}[http://www.ruby-lang.org/cgi-bin/cvsweb.cgi/ruby/lib/rdoc/parsers/parse_f95.rb] +ですが, 他のいくつかのプログラムにも改良を施しています. + +オリジナルの RDoc は Dave Thomas さんによって開発され, +現在では Ryan Davis さんによってメンテナンスされています. +オリジナルの RDoc は +Ruby の CVS レポジトリ +http://www.ruby-lang.org/ja/20020106.html +より取得できます. +オリジナルの RDoc に関しては +{RDoc オリジナルの README}[link:files/README_org.html] +を参照してください. + + +オリジナルからの変更点の主なものは以下の通りです. +なお, 既にこのパッチ (2005/12/17 バージョン) は +Ruby 本家の CVS リポジトリへとフィードバックされているので, +一部は既に「オリジナルとの変更点」 +ではなくなっていることに注意してください. + +--ignore-case オプションの追加 :: + Fortran 90/95 規格では大文字小文字の区別はありません. + これに対して, オリジナルの rdoc はクラス名やメソッド名の + クロスリファレンスの際に大文字小文字を区別します. + このオプションを与えることにより, + その区別を行わないようにします. + +ファイルのクロスリファレンス :: + クラスやモジュール, メソッドと同様に, ファイル名に関しても + クロスリファレンスを可能にしました. + +--style オプションの改良 :: + オリジナルの rdoc では, 相対パスでスタイルシートを指定した場合, + 各ドキュメントのスタイルシートへのパスが正しく設定されません. + このパッチを適用することで, 正しく設定されるようになります. + +TeX で書かれた数式の MathML への変換 :: + {ひらくの工房}[http://www.hinet.mydns.jp/~hiraku/] + にて公開されている + Ruby 用 MathML ライブラリのバージョン 0.5 を + インストールすることで, TeX で書かれた数式を + MathML に変換することが可能です. この機能を有効 + にするためには rdoc コマンドに --mathml オプションを + 指定してください. + TeX で数式を書く際の書式に関しては + Generators::TexParser を参照してください. + + ※ 注意 ※ --mathml オプションを使用した際に作成される + ドキュメントは + {Mozilla Firefox}[http://www.mozilla.or.jp/products/firefox/] + および Internet Explorer + (+ {MathPlayer}[http://www.dessci.com/en/products/mathplayer/]) + では正しく表示されることを確認しています. + その他のブラウザの MathML 対応に関しては, + {MathML 日本語情報}[http://washitake.com/MathML/] + や {MathML Software - Browsers}[http://www.w3.org/Math/Software/mathml_software_cat_browsers.html] + などを参照してください. + +-- +# 以降は Fortran とは関係の無い改変 +# +#Ruby ライブラリ IRB::SLex の読み込みについて :: +# Ruby 1.8.2 でも動作するよう, 最新の parse_rb.rb を１つ以前の +# バージョンに戻しています. +# +# +#拡張子cxxも C パーサで解釈 :: +# これは全く Fortran 90/95 とは関係ありません. +# この拡張子 cxx は c++ ファイルから +# SWIG[http://swig.shibu.jp/] によって作成されるファイルの拡張子です. +++ + +解析能力が向上されたのに伴い, ドキュメントに反映されるコメントの書法の +多少変更されています. +parsers/parse_f95.rb を参照してください. + + +== 使用上の注意 + +RDoc Fortran 90/95 ソースコード解析機能強化版のパッチもしくはパッケージ +(以下, 本パッチもしくはパッケージ)は, +研究・教育の場で用いられることを前提としております. 教育現場においては自由に使用・改変していただいて結構です. +ライセンス規定は本家 RDoc に準拠します. +{RDoc オリジナルの README}[link:files/README_org.html] +を参照ください. + +本パッチもしくはパッケージを利用して得られた科学技術的成果を +論文や Web 等にて発表する際には, その旨を記し, リファレンスに挙げて +頂きますようお願いします. + +* 引用例 (和文) + + 森川 靖大, 石渡 正樹, 堀之内 武, 小高 正嗣, 林 祥介, + 数値モデリングプロジェクト dcmodel, 2006: + RDoc Fortran 90/95 ソースコード解析機能強化版, + http://www.gfd-dennou.org/library/dcmodel/, 地球流体電脳倶楽部. + +* 引用例 (英文) + + Morikawa,Y., Ishiwatari,M., Horinouchi,T., Odaka,M., Hayashi,Y.-Y., + dcmodel: Numerical Model Porject, 2006: + Enhanced version of RDoc Fortran 90/95 parser, + http://www.gfd-dennou.org/library/dcmodel/, GFD Dennou Club. + + +== 連絡先 + +{数値モデリングプロジェクト dcmodel}[http://www.gfd-dennou.org/library/dcmodel/] +のページ末尾を参照ください. + + +== 履歴 + +==== 2006/08/14 + +* パッケージ名を rdoc-dennou から rdoc-f95 に変更. +* 公開アドレスを + http://www.gfd-dennou.org/library/dcmodel/rdoc-dennou/ から + http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/ へ変更. + (過去の URL もしばらく残しておきます). +* README, README.ja の修正. +* TeX で書かれた数式を MathML への変換する機能を追加. +* style オプションの改良. +* 主プログラムも 'Methods' の欄に追加. +* 各ファイルに点在している NAMELIST 変数群を自動的に一箇所に + 集約して表示するよう改良. +* F90 ファイルが提供するモジュール群の名前を, + 自動的にファイルのドキュメントに追記するよう改良. + + +==== 2006/02/24 + +* 英語版 README の作成 + +* README.ja の修正. + + +==== 2006/01/18 +* サブルーチン, 関数の引数の情報をコメントとして出力する際の書式を + 少しだけ修正. + + * 引数情報をコメントに出力する際, 引数の後ろに空白を挿入した. + これにより, メソッドの並び替えを行う際 (メソッドはメソッド名, + 引数, コメントの順に大きさを比較し, 並べる順序を決める), + "args" が "args(:)" よりも前に来るようになる. + +* 本家 Ruby の CVS リポジトリ内の更新を受け, 最新版をこちらの + パッケージ版にも移植. + +==== 2005/12/28 +* ruby 1.8.4 のリリースに伴い, パッチを 1.8.4 用に変更. + +==== 2005/12/17 + +* 同名の手続き同士で公開・非公開属性を誤って設定してしまうバグを修正. +* 以下のバグを修正 + * program, module, subroutine, function の end 文は必ず + end program, end module, end subroutine, end function のように + 記述しないと, 書法を正しく解析出来ない. + * program 〜 end program 文の, 最初と最後の program という文字を + 省略した場合, program 文の内部で定義されるものは全て public だと + 認識される. + * ";" の文字をコメント内でも改行に変換してしまう +* !-- 〜 !++ によるコメント削除の指定の際に, "!" よりも前に空白を + 含んでよいように修正. +* interface 文で指定される外部手続きの解析を修正. +* 継続行の扱いを修正. + +==== 2005/12/13 + +* parsers/parse_f95.rb に注意事項と Todo を追加. +* 「サンプル」を追加. +* public, private 文を解析する部分のバグを修正. + +==== 2005/12/08 + +* 「使用上の注意」, 「連絡先」を追加. +* 公開アドレスを + http://www.gfd-dennou.org/library/dcmodel/doc/rdoc-dennou/ から + http://www.gfd-dennou.org/library/dcmodel/rdoc-dennou/ へ変更. + (過去の URL もしばらく残しておきます). + +==== 2005/11/28 + +* ":nodoc:" の指定を可能にする. +* サブルーチンや関数内の "contains" 文の処理方法を修正する. +* 表題を変更する. +* 過去のバージョンを公開する. + +==== 2005/11/17 + +* 一通り欲しい機能が揃い, ドキュメントのチェックも行ったので, + タグをつけて公開する. diff -Nur --exclude=doc ruby-1.8.4/lib/rdoc/README.org ../rdoc-f95-20060814/README.org --- ruby-1.8.4/lib/rdoc/README.org 1970-01-01 09:00:00.000000000 +0900 +++ ../rdoc-f95-20060814/README.org 2006-07-08 14:56:44.000000000 +0900 @@ -0,0 +1,502 @@ += RDOC - Ruby Documentation System + +== Annotation + +This is a copy from +{RDoc original README}[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html] + +See README or README.ja . + +== Overview + +This package contains Rdoc and SimpleMarkup. Rdoc is an application +that produces documentation for one or more Ruby source files. We work +similarly to JavaDoc, parsing the source, and extracting the +definition for classes, modules, and methods (along with includes and +requires). We associate with these optional documentation contained +in the immediately preceding comment block, and then render the result +using a pluggable output formatter. (Currently, HTML is the only +supported format. Markup is a library that converts plain text into +various output formats. The Markup library is used to interpret the +comment blocks that Rdoc uses to document methods, classes, and so on. + +This library contains two packages, rdoc itself and a text markup +library, 'markup'. + +== Roadmap + +* If you want to use Rdoc to create documentation for your Ruby source + files, read on. +* If you want to include extensions written in C, see rdoc/parsers/parse_c.rb. +* For information on the various markups available in comment + blocks, see markup/simple_markup.rb. +* If you want to drive Rdoc programatically, see RDoc::RDoc. +* If you want to use the library to format text blocks into HTML, + have a look at SM::SimpleMarkup. +* If you want to try writing your own HTML output template, see + RDoc::Page. + +== Summary + +Once installed, you can create documentation using the 'rdoc' command +(the command is 'rdoc.bat' under Windows) + + % rdoc [options] [names...] + +Type "rdoc --help" for an up-to-date option summary. + +A typical use might be to generate documentation for a package of Ruby +source (such as rdoc itself). + + % rdoc + +This command generates documentation for all the Ruby and C source +files in and below the current directory. These will be stored in a +documentation tree starting in the subdirectory 'doc'. + +You can make this slightly more useful for your readers by having the +index page contain the documentation for the primary file. In our +case, we could type + + % rdoc --main rdoc/rdoc.rb + +You'll find information on the various formatting tricks you can use +in comment blocks in the documentation this generates. + +RDoc uses file extensions to determine how to process each file. File +names ending .rb and .rbw are assumed to be Ruby +source. Files ending .c are parsed as C files. All other +files are assumed to contain just SimpleMarkup-style markup (with or +without leading '#' comment markers). If directory names are passed to +RDoc, they are scanned recursively for C and Ruby source files only. + +== Credits + +* The Ruby parser in rdoc/parse.rb is based heavily on the outstanding + work of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby + parser for irb and the rtags package. + +* Code to diagram classes and modules was written by Sergey A Yanovitsky + (Jah) of Enticla. + +* Charset patch from MoonWolf. + +* Rich Kilmer wrote the kilmer.rb output template. + +* Dan Brickley led the design of the RDF format. + +== License + +RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. It +is free software, and may be redistributed under the terms specified +in the README file of the Ruby distribution. + + += Usage + +RDoc is invoked from the command line using: + + % rdoc [name...] + +Files are parsed, and the information they contain collected, before +any output is produced. This allows cross references between all files +to be resolved. If a name is a directory, it is traversed. If no +names are specified, all Ruby files in the current directory (and +subdirectories) are processed. + +Options are: + +[--accessor name[,name...]] + specifies the name(s) of additional methods that should be treated + as if they were attr_xxx methods. Specifying + "--accessor db_opt" means lines such as + + db_opt :name, :age + + will get parsed and displayed in the documentation. Each name may have an + optional "=flagtext" appended, in which case the given flagtext will appear + where (for example) the 'rw' appears for attr_accessor. + +[--all] + include protected and private methods in the output (by default + only public methods are included) + +[--charset _charset_] + Set the character set for the generated HTML. + +[--diagram] + include diagrams showing modules and classes. This is currently + an experimental feature, and may not be supported by all output + templates. You need dot V1.8.6 or later to use the --diagram + option correctly (http://www.research.att.com/sw/tools/graphviz/). + +[--exclude pattern] + exclude files and directories matching this pattern from processing + +[--extension new=old] + treat files ending .new as if they ended + .old. Saying '--extension cgi=rb' causes RDoc to treat .cgi + files as Ruby source. + +[fileboxes] + Classes are put in boxes which represents files, where these + classes reside. Classes shared between more than one file are + shown with list of files that sharing them. Silently discarded if + --diagram is not given Experimental. + +[--fmt _fmt_] + generate output in a particular format. + +[--help] + generate a usage summary. + +[--help-output] + explain the various output options. + +[--ignore-case] + The case of names of classes or modules or methods are ignored. + +[--image-format gif/png/jpg/jpeg] + sets output image format for diagrams. Can be png, gif, jpeg, + jpg. If this option is omitted, png is used. Requires --diagram. + +[--include dir,...] + specify one or more directories to be searched when satisfying + :+include+: directives. Multiple --include options may be + given. The directory containing the file currently being processed + is always searched. + +[--inline-source] + By default, the source code of methods is shown in a popup. With + this option, it's displayed inline. + +[line-numbers] + include line numbers in the source code + +[--main _name_] + the class of module _name_ will appear on the index page. If you + want to set a particular file as a main page (a README, for + example) simply specifiy its name as the first on the command + line. + +[--merge] + when generating _ri_ output, if classes being processed already + exist in the destination directory, merge in the current details + rather than overwrite them. + +[--one-file] + place all the output into a single file + +[--op _dir_] + set the output directory to _dir_ (the default is the directory + "doc") + +[--op-name _name_] + set the name of the output. Has no effect for HTML. + "doc") + +[--opname _name_] + set the output name (has no effect for HTML). + +[--promiscuous] + If a module or class is defined in more than one source file, and + you click on a particular file's name in the top navigation pane, + RDoc will normally only show you the inner classes and modules of + that class that are defined in the particular file. Using this + option makes it show all classes and modules defined in the class, + regardless of the file they were defined in. + +[--quiet] + do not display progress messages + +[--ri, --ri-site, _and_ --ri-system] + generate output than can be read by the _ri_ command-line tool. + By default --ri places its output in ~/.rdoc, --ri-site in + $datadir/ri//site, and --ri-system in + $datadir/ri//system. All can be overridden with a subsequent + --op option. All default directories are in ri's default search + path. + +[--show-hash] + A name of the form #name in a comment is a possible hyperlink to + an instance method name. When displayed, the '#' is removed unless + this option is specified + +[--style stylesheet url] + specifies the URL of an external stylesheet to use (rather than + generating one of our own) + +[tab-width _n_] + set the width of tab characters (default 8) + +[--template name] + specify an alternate template to use when generating output (the + default is 'standard'). This template should be in a directory + accessible via $: as rdoc/generators/xxxx_template, where 'xxxx' + depends on the output formatter. + +[--version] + display RDoc's version + +[--webcvs _url_] + Specify a URL for linking to a web frontend to CVS. If the URL + contains a '\%s', the name of the current file will be + substituted; if the URL doesn't contain a '\%s', the filename will + be appended to it. + += Example + +A typical small Ruby program commented using RDoc might be as follows. You +can see the formatted result in EXAMPLE.rb and Anagram. + + :include: EXAMPLE.rb + += Markup + +Comment blocks can be written fairly naturally, either using '#' on +successive lines of the comment, or by including the comment in +an =begin/=end block. If you use the latter form, the =begin line +must be flagged with an RDoc tag: + + =begin rdoc + Documentation to + be processed by RDoc. + =end + +Paragraphs are lines that share the left margin. Text indented past +this margin are formatted verbatim. + +1. Lists are typed as indented paragraphs with: + * a '*' or '-' (for bullet lists) + * a digit followed by a period for + numbered lists + * an upper or lower case letter followed + by a period for alpha lists. + + For example, the input that produced the above paragraph looked like + 1. Lists are typed as indented + paragraphs with: + * a '*' or '-' (for bullet lists) + * a digit followed by a period for + numbered lists + * an upper or lower case letter followed + by a period for alpha lists. + +2. Labeled lists (sometimes called description + lists) are typed using square brackets for the label. + [cat] small domestic animal + [+cat+] command to copy standard input + +3. Labeled lists may also be produced by putting a double colon + after the label. This sets the result in tabular form, so the + descriptions all line up. This was used to create the 'author' + block at the bottom of this description. + cat:: small domestic animal + +cat+:: command to copy standard input + + For both kinds of labeled lists, if the body text starts on the same + line as the label, then the start of that text determines the block + indent for the rest of the body. The text may also start on the line + following the label, indented from the start of the label. This is + often preferable if the label is long. Both the following are + valid labeled list entries: + + --output name [, name]:: + specify the name of one or more output files. If multiple + files are present, the first is used as the index. + + --quiet::: do not output the names, sizes, byte counts, + index areas, or bit ratios of units as + they are processed. + +4. Headings are entered using equals signs + + = Level One Heading + == Level Two Heading + and so on + +5. Rules (horizontal lines) are entered using three or + more hyphens. + +6. Non-verbatim text can be marked up: + + _italic_:: \_word_ or \text + *bold*:: \*word* or \text + +typewriter+:: \+word+ or \text + + The first form only works around 'words', where a word is a + sequence of upper and lower case letters and underscores. Putting a + backslash before inline markup stops it being interpreted, which is + how I created the table above: + + _italic_:: \_word_ or \text + *bold*:: \*word* or \text + +typewriter+:: \+word+ or \text + +7. Names of classes, source files, and any method names + containing an underscore or preceded by a hash + character are automatically hyperlinked from + comment text to their description. + +8. Hyperlinks to the web starting http:, mailto:, ftp:, or www. are + recognized. An HTTP url that references an external image file is + converted into an inline . Hyperlinks starting 'link:' are + assumed to refer to local files whose path is relative to the --op + directory. + + Hyperlinks can also be of the form label[url], in which + case the label is used in the displayed text, and url is + used as the target. If label contains multiple words, + put it in braces: {multi word label}[url]. + +9. Method parameter lists are extracted and displayed with + the method description. If a method calls +yield+, then + the parameters passed to yield will also be displayed: + + def fred + ... + yield line, address + + This will get documented as + + fred() { |line, address| ... } + + You can override this using a comment containing + ':yields: ...' immediately after the method definition + + def fred # :yields: index, position + ... + yield line, address + + which will get documented as + + fred() { |index, position| ... } + + +10. ':yields:' is an example of a documentation modifier. These appear + immediately after the start of the document element they are modifying. + Other modifiers include + + [:nodoc:[all]] + don't include this element in the documentation. For classes + and modules, the methods, aliases, constants, and attributes + directly within the affected class or module will also be + omitted. By default, though, modules and classes within that + class of module _will_ be documented. This is turned off by + adding the +all+ modifier. + + module SM #:nodoc: + class Input + end + end + module Markup #:nodoc: all + class Output + end + end + + In the above code, only class SM::Input will be + documented. + + [:doc:] + force a method or attribute to be documented even if it + wouldn't otherwise be. Useful if, for example, you want to + include documentation of a particular private method. + + [:notnew:] + only applicable to the +initialize+ instance method. Normally + RDoc assumes that the documentation and parameters for + #initialize are actually for the ::new method, and so fakes + out a ::new for the class. THe :notnew: modifier stops + this. Remember that #initialize is protected, so you won't + see the documentation unless you use the -a command line + option. + + +11. RDoc stops processing comments if it finds a comment + line containing '#--'. This can be used to + separate external from internal comments, or + to stop a comment being associated with a method, + class, or module. Commenting can be turned back on with + a line that starts '#++'. + + # Extract the age and calculate the + # date-of-birth. + #-- + # FIXME: fails if the birthday falls on + # February 29th + #++ + # The DOB is returned as a Time object. + + def get_dob(person) + ... + +12. Comment blocks can contain other directives: + + [:section: title] + Starts a new section in the output. The title following + :section: is used as the section heading, and the + remainder of the comment containing the section is used as + introductory text. Subsequent methods, aliases, attributes, + and classes will be documented in this section. A :section: + comment block may have one or more lines before the :section: + directive. These will be removed, and any identical lines at + the end of the block are also removed. This allows you to add + visual cues such as + + # ---------------------------------------- + # :section: My Section + # This is the section that I wrote. + # See it glisten in the noon-day sun. + # ---------------------------------------- + + [call-seq:] + lines up to the next blank line in the comment are treated as + the method's calling sequence, overriding the + default parsing of method parameters and yield arguments. + + [:include:filename] + include the contents of the named file at this point. The + file will be searched for in the directories listed by + the --include option, or in the current + directory by default. The contents of the file will be + shifted to have the same indentation as the ':' at the + start of the :include: directive. + + [:title:text] + Sets the title for the document. Equivalent to the --title command + line parameter. (The command line parameter overrides any :title: + directive in the source). + + [:enddoc:] + Document nothing further at the current level. + + [:main:name] + Equivalent to the --main command line parameter. + + [:stopdoc: / :startdoc:] + Stop and start adding new documentation elements to the + current container. For example, if a class has a number of + constants that you don't want to document, put a + :stopdoc: before the first, and a + :startdoc: after the last. If you don't specifiy a + :startdoc: by the end of the container, disables + documentation for the entire class or module. + + +--- + +See also markup/simple_markup.rb. + += Other stuff + +Author:: Dave Thomas +Requires:: Ruby 1.8.1 or later +License:: Copyright (c) 2001-2003 Dave Thomas. + Released under the same license as Ruby. + +== Warranty + +This software is provided "as is" and without any express or +implied warranties, including, without limitation, the implied +warranties of merchantibility and fitness for a particular +purpose. diff -Nur --exclude=doc ruby-1.8.4/lib/rdoc/code_objects.rb ../rdoc-f95-20060814/code_objects.rb --- ruby-1.8.4/lib/rdoc/code_objects.rb 2004-12-04 14:38:15.000000000 +0900 +++ ../rdoc-f95-20060814/code_objects.rb 2005-12-16 09:29:36.000000000 +0900 @@ -235,8 +235,12 @@ end def add_method(a_method) - puts "Adding #@visibility method #{a_method.name} to #@name" if $DEBUG - a_method.visibility = @visibility + if !(a_method.visibility == :public) && + !(a_method.visibility == :private) && + !(a_method.visibility == :protected) + a_method.visibility = @visibility + end + puts "Adding #{a_method.visibility} method #{a_method.name} to #@name" if $DEBUG add_to(@method_list, a_method) end @@ -244,8 +248,8 @@ add_to(@attributes, an_attribute) end - def add_alias(an_alias) - meth = find_instance_method_named(an_alias.old_name) + def add_alias(an_alias, ignore_case=nil) + meth = find_instance_method_named(an_alias.old_name, ignore_case) if meth new_meth = AnyMethod.new(an_alias.text, an_alias.new_name) new_meth.is_alias_for = meth @@ -325,16 +329,34 @@ end # Find a named module - def find_module_named(name) - return self if self.name == name - res = @modules[name] || @classes[name] + def find_module_named(name, ignore_case=nil) + res = nil + if !ignore_case + return self if self.name == name + else + return self if self.name.upcase == name.upcase + end + if !ignore_case + res = @modules[name] || @classes[name] + else + @modules.each{ |n, v| + if n.upcase == name.upcase + res = v ; break + end + } + @classes.each{ |n, v| + if n.upcase == name.upcase + res = v ; break + end + } if !res + end return res if res - find_enclosing_module_named(name) + find_enclosing_module_named(name, ignore_case) end # find a module at a higher scope - def find_enclosing_module_named(name) - parent && parent.find_module_named(name) + def find_enclosing_module_named(name, ignore_case=nil) + parent && parent.find_module_named(name, ignore_case) end # Iterate over all the classes and modules in @@ -357,6 +379,10 @@ @constants.each {|c| yield c} end + def each_includes + @includes.each {|i| yield i} + end + # Return the toplevel that owns us def toplevel @@ -371,22 +397,27 @@ name <=> other.name end + # Look up the given filename. + def find_file(file, method=nil, ignore_case=nil) + find_file_named(file, method, ignore_case) + end + # Look up the given symbol. If method is non-nil, then # we assume the symbol references a module that # contains that method - def find_symbol(symbol, method=nil) + def find_symbol(symbol, method=nil, ignore_case=nil) result = nil case symbol when /^::(.*)/ - result = toplevel.find_symbol($1) + result = toplevel.find_symbol($1, nil, ignore_case) when /::/ modules = symbol.split(/::/) unless modules.empty? module_name = modules.shift - result = find_module_named(module_name) + result = find_module_named(module_name, ignore_case) if result modules.each do |module_name| - result = result.find_module_named(module_name) + result = result.find_module_named(module_name, ignore_case) break unless result end end @@ -395,11 +426,12 @@ # if a method is specified, then we're definitely looking for # a module, otherwise it could be any symbol if method - result = find_module_named(symbol) + result = find_module_named(symbol, ignore_case) else - result = find_local_symbol(symbol) + result = find_local_symbol(symbol, ignore_case) if result.nil? - if symbol =~ /^[A-Z]/ + if symbol =~ /^[A-Z]/ || + symbol =~ /^[A-Za-z]/ && ignore_case result = parent while result && result.name != symbol result = result.parent @@ -414,16 +446,40 @@ p method fail end - result = result.find_local_symbol(method) + result = result.find_local_symbol(method, ignore_case) end result end - - def find_local_symbol(symbol) - res = find_method_named(symbol) || - find_constant_named(symbol) || - find_attribute_named(symbol) || - find_module_named(symbol) + + def find_local_symbol(symbol, ignore_case=nil) + res = find_method_named(symbol, ignore_case) || + find_constant_named(symbol, ignore_case) || + find_attribute_named(symbol, ignore_case) || + find_module_named(symbol, ignore_case) + end + + def include_requires?(name, ignore_case=nil) + if self.kind_of? TopLevel + self.requires.each{|r| + if r.name == name || + r.name.upcase == name.upcase && ignore_case + return true + end + } + return false + else + parent.include_requires?(name) + end + end + + def include_includes?(name, ignore_case=nil) + self.includes.each{|i| + if i.name == name || + i.name.upcase == name.upcase && ignore_case + return true + end + } + return false end # Handle sections @@ -436,25 +492,43 @@ private # Find a named method, or return nil - def find_method_named(name) - @method_list.find {|meth| meth.name == name} + def find_method_named(name, ignore_case=nil) + if !ignore_case + @method_list.find {|meth| meth.name == name} + else + @method_list.find {|meth| meth.name.upcase == name.upcase} + end end # Find a named instance method, or return nil - def find_instance_method_named(name) - @method_list.find {|meth| meth.name == name && !meth.singleton} + def find_instance_method_named(name, ignore_case=nil) + if !ignore_case + @method_list.find {|meth| meth.name == name && !meth.singleton} + else + @method_list.find {|meth| + meth.name.upcase == name.upcase && !meth.singleton + } + end end # Find a named constant, or return nil - def find_constant_named(name) - @constants.find {|m| m.name == name} + def find_constant_named(name, ignore_case=nil) + if !ignore_case + @constants.find {|m| m.name == name} + else + @constants.find {|m| m.name.upcase == name.upcase} + end end # Find a named attribute, or return nil - def find_attribute_named(name) - @attributes.find {|m| m.name == name} + def find_attribute_named(name, ignore_case=nil) + if !ignore_case + @attributes.find {|m| m.name == name} + else + @attributes.find {|m| m.name.upcase == name.upcase} + end end - + end @@ -465,13 +539,15 @@ attr_accessor :file_relative_name attr_accessor :file_absolute_name attr_accessor :diagram - + @@all_classes = {} @@all_modules = {} + @@all_files = {} def TopLevel::reset @@all_classes = {} @@all_modules = {} + @@all_files = {} end def initialize(file_name) @@ -481,6 +557,7 @@ @file_absolute_name = file_name @file_stat = File.stat(file_name) @diagram = nil + @@all_files[file_name] = self end def full_name @@ -519,6 +596,10 @@ @@all_classes.values + @@all_modules.values end + def TopLevel.all_files + @@all_files + end + def TopLevel.find_class_named(name) @@all_classes.each_value do |c| res = c.find_class_named(name) @@ -527,21 +608,50 @@ nil end - def find_local_symbol(symbol) - find_class_or_module_named(symbol) || super + def find_local_symbol(symbol, ignore_case=nil) + find_class_or_module_named(symbol, ignore_case) || super end - def find_class_or_module_named(symbol) - @@all_classes.each_value {|c| return c if c.name == symbol} - @@all_modules.each_value {|m| return m if m.name == symbol} + def find_class_or_module_named(symbol, ignore_case=nil) + if !ignore_case + @@all_classes.each_value {|c| return c if c.name == symbol} + @@all_modules.each_value {|m| return m if m.name == symbol} + else + @@all_classes.each_value {|c| return c if c.name.upcase == symbol.upcase} + @@all_modules.each_value {|m| return m if m.name.upcase == symbol.upcase} + end nil end # Find a named module - def find_module_named(name) - find_class_or_module_named(name) || find_enclosing_module_named(name) + def find_module_named(name, ignore_case=nil) + find_class_or_module_named(name, ignore_case) || find_enclosing_module_named(name, ignore_case) end + # Find a named file + def find_file_named(name, method=nil, ignore_case=nil) + return nil unless name + result = nil + @@all_files.each{|file_name, toplevel| + result = toplevel if file_name == name + } + dir = File.dirname(@file_relative_name) + @@all_files.each{|file_name, toplevel| + if /^#{dir}\/(.*)/ =~ file_name + result = toplevel if $1 == name + end + } + if result + if method + result_method = result.find_local_symbol(method, ignore_case) + return result_method + else + return result + end + else + return nil + end + end end @@ -593,6 +703,11 @@ @classes.each_value {|c| return c if c.find_class_named(name) } nil end + + def find_file_named(name, method=nil, ignore_case=nil) + parent.find_file_named(name, method, ignore_case) + end + end # Anonymous classes @@ -648,7 +763,11 @@ end def <=>(other) - @name <=> other.name + t = @name <=> other.name + return t if t != 0 + t = @params <=> other.params + return t if t != 0 + t = @comment <=> other.comment end def to_s @@ -689,7 +808,7 @@ # with a particular context class Alias < CodeObject attr_accessor :text, :old_name, :new_name, :comment - + def initialize(text, old_name, new_name, comment) super() @text = text diff -Nur --exclude=doc ruby-1.8.4/lib/rdoc/diagram.rb ../rdoc-f95-20060814/diagram.rb --- ruby-1.8.4/lib/rdoc/diagram.rb 2004-07-17 05:27:29.000000000 +0900 +++ ../rdoc-f95-20060814/diagram.rb 2006-07-31 15:17:16.000000000 +0900 @@ -38,6 +38,10 @@ @options = options @counter = 0 File.makedirs(DOT_PATH) + @html_suffix = ".html" + if @options.mathml + @html_suffix = ".xhtml" + end end # Draw the diagrams. We traverse the files, drawing a diagram for @@ -128,7 +132,7 @@ return if @done_modules[mod.full_name] and not toplevel @counter += 1 - url = mod.http_url("classes") + url = mod.http_url("classes").sub(/\.html$/, @html_suffix) m = DOT::DOTSubgraph.new('name' => "cluster_#{mod.full_name.gsub( /:/,'_' )}", 'label' => mod.name, 'fontname' => FONT, @@ -152,7 +156,7 @@ else unless @global_names.include?(m_full_name) path = m_full_name.split("::") - url = File.join('classes', *path) + ".html" + url = File.join('classes', *path) + @html_suffix @global_graph << DOT::DOTNode.new('name' => "#{m_full_name.gsub( /:/,'_' )}", 'shape' => 'box', 'label' => "#{m_full_name}", @@ -198,7 +202,7 @@ next if cl.name == 'Object' || cl.name[0,2] == "<<" - url = cl.http_url("classes") + url = cl.http_url("classes").sub(/\.html$/, @html_suffix) label = cl.name.dup if use_fileboxes && cl.in_files.length > 1 @@ -245,7 +249,7 @@ else unless @global_names.include?(m_full_name) path = m_full_name.split("::") - url = File.join('classes', *path) + ".html" + url = File.join('classes', *path) + @html_suffix @global_graph << DOT::DOTNode.new('name' => "#{m_full_name.gsub( /:/,'_' )}", 'shape' => 'box', 'label' => "#{m_full_name}", @@ -262,7 +266,7 @@ sclass_full_name = find_full_name(sclass,cl) unless @local_names.include?(sclass_full_name) or @global_names.include?(sclass_full_name) path = sclass_full_name.split("::") - url = File.join('classes', *path) + ".html" + url = File.join('classes', *path) + @html_suffix @global_graph << DOT::DOTNode.new( 'name' => "#{sclass_full_name.gsub( /:/, '_' )}", 'label' => sclass_full_name, @@ -295,7 +299,7 @@ f << graph.to_s << "\n" end - system "dot -T#{op_type} #{src} -o #{dot}" + system "dot", "-T#{op_type}", src, "-o", dot # Now construct the imagemap wrapper around # that png @@ -320,13 +324,13 @@ xs, ys = [$1.to_i, $3.to_i], [$2.to_i, $4.to_i] url, area_name = $5, $6 - res << %{ #{area_name}\n} + res << %{ #{area_name}\n} end res << "\n" # map_file = src.sub(/.dot/, '.map') # system("dot -Timap #{src} -o #{map_file}") - res << %{#{name}} + res << %{#{name}} return res end end diff -Nur --exclude=doc ruby-1.8.4/lib/rdoc/generators/chm_generator.rb ../rdoc-f95-20060814/generators/chm_generator.rb --- ruby-1.8.4/lib/rdoc/generators/chm_generator.rb 2003-12-01 16:12:48.000000000 +0900 +++ ../rdoc-f95-20060814/generators/chm_generator.rb 2005-09-22 16:49:18.000000000 +0900 @@ -4,7 +4,7 @@ class CHMGenerator < HTMLGenerator - HHC_PATH = "c:\\Program Files\\HTML Help Workshop\\hhc.exe" + HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe" # Standard generator factory def CHMGenerator.for(options) @@ -103,7 +103,7 @@ # Invoke the windows help compiler to compiler the project def compile_project - system("\"#{HHC_PATH}\" #@project_name") + system(HHC_PATH, @project_name) end end diff -Nur --exclude=doc ruby-1.8.4/lib/rdoc/generators/html_generator.rb ../rdoc-f95-20060814/generators/html_generator.rb --- ruby-1.8.4/lib/rdoc/generators/html_generator.rb 2005-02-12 19:57:20.000000000 +0900 +++ ../rdoc-f95-20060814/generators/html_generator.rb 2006-08-05 00:43:59.000000000 +0900 @@ -114,7 +114,12 @@ lookup = name end - if /([A-Z].*)[.\#](.*)/ =~ lookup + # Find class, module, or method in class or module. + if /([A-Z]\w*)[.\#](\w+[!?=]?)/ =~ lookup + container = $1 + method = $2 + ref = @context.find_symbol(container, method) + elsif /([A-Za-z]\w*)[.\#](\w+(\([\.\w+\*\/\+\-\=\<\>]+\))?)/ =~ lookup container = $1 method = $2 ref = @context.find_symbol(container, method) @@ -129,6 +134,30 @@ end end + # + # CROSSREFFILE is similar to CROSSREF. But this pattern is + # hit to filenames or methods in files + # + def handle_special_CROSSREFFILE(special) + name = special.text + + # Find file, or method in file + if /([\w\/].*\.\w+)[.\#](.*)/ =~ name + file_name = $1 + method = $2 + ref = @context.find_file(file_name, method) + else + ref = @context.find_file(name) + end + + if ref and ref.document_self + "#{name}" + else + name + end + + end + # Generate a hyperlink for url, labeled with text. Handle the # special cases for img: and link: described under handle_special_HYPEDLINK @@ -153,9 +182,12 @@ if (type == "http" || type == "link") && url =~ /\.(gif|png|jpg|jpeg|bmp)$/ - "" - else + "" + + elsif type == "link" "#{text.sub(%r{^#{type}:/*}, '')}" + else + "#{text.sub(%r{^#{type}:/*}, '')}" end end @@ -206,15 +238,24 @@ unless defined? @markup @markup = SM::SimpleMarkup.new - # class names, variable names, file names, or instance variables + # class names, variable names, or instance variables @markup.add_special(/( - \b([A-Z]\w*(::\w+)*[.\#]\w+) # A::B.meth + \b\w+(::\w+)*[\.\#]\w+(\([\.\w+\*\/\+\-\=\<\>]+\))? # A::B.meth(**) (for operator in Fortran95) + | \#\w+(\([.\w\*\/\+\-\=\<\>]+\))? # meth(**) (for operator in Fortran95) + | \b([A-Z]\w*(::\w+)*[.\#]\w+) # A::B.meth | \b([A-Z]\w+(::\w+)*) # A::B.. | \#\w+[!?=]? # #meth_name - | \b\w+([_\/\.]+\w+)+[!?=]? # meth_name + | \b\w+([_\/\.]+\w+)*[!?=]? # meth_name )/x, :CROSSREF) + # file names + @markup.add_special(/( + \b(\w[\w\#\/\.\-\~\:]*[!?=]?) # file_name + | \b(\w[\w\#\/\.\-\~\:]*(\([\.\w+\*\/\+\-\=\<\>]+\))?) + )/x, + :CROSSREFFILE) + # external hyperlinks @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK) @@ -283,12 +324,12 @@ include MarkUp attr_reader :context - + def initialize(context, options) @context = context @options = options end - + # convenience method to build a hyperlink def href(link, cls, name) %{#{name}} #" @@ -397,7 +438,8 @@ # end # end - ref = @context.find_symbol(i.name) + ref = @context.find_symbol(i.name, nil, @options.ignore_case) || \ + @context.find_file(i.name) ref = ref.viewer if ref if !ref && block_given? @@ -546,7 +588,17 @@ # Find a symbol in ourselves or our parent def find_symbol(symbol, method=nil) - res = @context.find_symbol(symbol, method) + res = @context.find_symbol(symbol, method, @options.ignore_case) + if res + res = res.viewer + end + res + end + + # Find a filenames in ourselves or our parent + def find_file(file, method=nil) + res = @context.find_file(file, method, + @options.ignore_case) if res res = res.viewer end @@ -607,7 +659,7 @@ if path['<<'] path.gsub!(/<<\s*(\w*)/) { "from-#$1" } end - File.join(prefix, path.split("::")) + ".html" + File.join(prefix, path.split("::")) + '.' + @options.template end @@ -784,7 +836,7 @@ def http_url(file_dir) File.join(file_dir, @context.file_relative_name.tr('.', '_')) + - ".html" + '.' + @options.template end def filename_to_label @@ -1017,9 +1069,10 @@ end def create_source_code_file(code_body) - meth_path = @html_class.path.sub(/\.html$/, '.src') + template_regexp = Regexp.new("\\." + @options.template + "$") + meth_path = @html_class.path.sub(template_regexp, '.src') File.makedirs(meth_path) - file_path = File.join(meth_path, @seq) + ".html" + file_path = File.join(meth_path, @seq) + '.' + @options.template template = TemplatePage.new(RDoc::Page::SRC_PAGE) File.open(file_path, "w") do |f| @@ -1110,12 +1163,22 @@ end def find_symbol(symbol, method=nil) - res = @context.parent.find_symbol(symbol, method) + res = @context.parent.find_symbol(symbol, method, @options.ignore_case) + if res + res = res.viewer + end + res + end + + # Find a filenames in ourselves or our parent + def find_file(file, method=nil) + res = @context.parent.find_file(file, method) if res res = res.viewer end res end + end ##################################################################### @@ -1139,7 +1202,8 @@ from.shift to.shift end - + + from.delete_if{|f| f =~ /^\.$/} from.fill("..") from.concat(to) from << to_file diff -Nur --exclude=doc ruby-1.8.4/lib/rdoc/generators/template/html/hefss.rb ../rdoc-f95-20060814/generators/template/html/hefss.rb --- ruby-1.8.4/lib/rdoc/generators/template/html/hefss.rb 2003-12-01 16:12:48.000000000 +0900 +++ ../rdoc-f95-20060814/generators/template/html/hefss.rb 2006-01-18 03:07:14.000000000 +0900 @@ -114,7 +114,7 @@ %title% - +