setext

来自「nedit 是一款linux下的开发源码的功能强大的编辑器」· 代码 · 共 1,890 行 · 第 1/5 页

eval 'exec perl -S $0 ${1+"$@"}'
    if $running_under_some_shell;

#-----------------------------------------------------------------------------
#
# setext.pl -- Structure Enhanced Text Converter (to HTML or simple text)
# 
# $Id: setext,v 1.10.2.2 2003/10/02 07:27:54 edg Exp $
# 
# Copyright (c) 2000 Steven Haehn
# 
# This 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 2 of the License, or (at your option) any later  
# version.                                                                    
#                                                                             
# This software 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 Lesser General Public License
# for more details.                                                           
#                                                                             
# You should have received a copy of the GNU General Public License along with
# software; if not, write to the Free Software Foundation, Inc., 59 Temple    
# Place, Suite 330, Boston, MA  02111-1307 USA                                
# 
#-----------------------------------------------------------------------------
#
# The concept of setext documents is the brain child of Ian Feldman.
# Some typotag terms used herein were originally implemented in a perl script
# by Tony Sanders, which is the inspirational source for this work.
# This perl script understands the original typotags, plus extras needed for 
# hypertext links, conditional text, and variables.
#
# Samples of setext documents are regularly provided to those folks which
# receive the TidBITS publication from www.tidbits.com in their e-mail.
#
# This program is really two programs crammed into one file. The two separate
# pieces share lots of code. Instead of having 3 separate files, one of
# them being a perl library with the shared code, there was a desire to keep
# everything rolled up in one suitcase.
#
#-----------------------------------------------------------------------------
#
# GENERAL TRANSLATOR ROUTINES    NEDIT HELP SOURCE CODE GENERATION ROUTINES
#
# check_target_reference         collect_internal_hypertext_references
# count                          emit_copyright
# date                           emit_helpText
# emit_paragraph                 emit_helpTitles
# emit_setext_definition         emit_help_header
# extract_fields                 emit_help_label
# extract_menu_info              emit_help_menu
# extract_menu_init              emit_help_menu_text
# get_menu_item                  emit_help_topic
# get_setext                     get_menu_text
# is_member                      get_newline
# parse_setext                   get_style
# preserve_html                  get_style_name
# recover_extractions            is_known_link
# replace_underlines             locate_menu_text
# show_usage                     make_NEdit_menu_code
# to_state                       print_menu
# translate_setext               
#                                
#                                
# TYPOTAG TRANSLATION ROUTINES
# 
# help_bold_tt      text_bold_tt        html_bold_tt
# help_bullet_tt    text_bullet_tt      html_bullet_tt
# help_emit_line    text_emit_line      html_emit_line
# help_final        text_final          html_final
# help_finishing    text_finishing      html_finishing
# help_hot_tt       text_hot_tt         html_hot_tt
# help_indent       text_indent         html_indent
# help_init         text_init           html_init,  html_init_title
# help_italic_tt    text_italic_tt      html_italic_tt
# help_line_break   text_line_break     html_line_break
# help_list_tt      text_list_tt        html_list_tt
# help_line_tt      text_line_tt        html_line_tt
# help_quote_tt     text_quote_tt       html_quote_tt
# help_section_tt   text_section_tt     html_section_tt
# help_target_tt    text_target_tt      html_target_tt
# help_title        text_title          html_title
# help_underline_tt text_underline_tt   html_underline_tt
#
# help_fixed_styles                     html_enter_list,  html_leave_list
# help_proportional_styles              html_enter_pre,   html_leave_pre
# fix_target_tt                         html_enter_quote, html_leave_quote
#                                       html_emit_header, html_emit_footer
#                                       getHtmlAttributes
#
#-----------------------------------------------------------------------------

use Getopt::Long;   # for parsing the program command line (GetOptions)
use File::Basename; # for trimming off directory names from files (basename)
use English;

#-------------------------------------------------------------------------------

sub emit_version
{
    my $version = "1.9";
    my $date    = "Oct 01, 2003"; 
    
    print "$pgm: Version $version, $date.\n";
    exit 0;
}

#-------------------------------------------------------------------------------

sub show_usage
{
    print "\n";
    print "Usage: $pgm [ -dhtTVw ][-D directory][-H [hfile]][-S [htmlExt]] \\\n";
    print "              [-c conditional][-v name=value][setext_file [converted_file]]\n";
    print "\n";
    print "       $pgm {-mp} [-c conditional][-M menuSuffix][-v name=value] setext_file\n";
    print "\n";
    print "  The first form of $pgm is used to convert Structure Enhanced TEXT\n";
    print "  documents into HTML or simple text documents.\n";
    print "  The second form is specific to generating NEdit help menu code\n";
    print "  from a setext document with Menu and Help directives.\n";
    print "\n";
    print "  -c conditional text definitions, separated by commas.\n";
    print "  -d do not automatically make titles hypertext references (HTML only)\n";
    print "  -D specify destination directory for separate HTML files. This also sets\n";
    print "     the value for the variable HTML_DIR.\n";
    print "  -h show this usage clause.\n";
    print "  -H convert setext_file to HyperText Markup Language (HTML).\n";
    print "     Optional file parameter specifies file containing HTML header\n";
    print "     and footer definition overrides. The current defaults are:\n";
    print "        \$htmlHeader = <HTML>\n";
    print "                      <TITLE>\$HTML_TITLE</TITLE>\n";
    print "                      <HEAD></HEAD>\n";
    print "                      <BODY>\n";
    print "        \$htmlFooter = </BODY>\n";
    print "                      </HTML>\n";
    print "     where \$HTML_TITLE is replaced with an appropriate title.\n\n";
    print "  -m generate NEdit help menu code files.\n";
    print "  -M name NEdit help code files with this suffix.\n";
    print "  -p do option -m and print out NEdit help elements.\n";
    print "  -S convert setext_file into separate HTML files.\n";
    print "     (the default name extension is '$htmlExt', but it can be\n";
    print "     changed by specifying it as an argument to this option)\n";
    print "  -t convert setext_file to simple text (default).\n";
    print "  -T emit setext typotag definitions in use.\n";
    print "  -v defines variable name and assigns it the given value.\n";
    print "     (more than one occurrence of -v can be made) The variables\n";
    print "     are made available for use within the setext document parsing.\n";
    print "  -V display the version of this setext script.\n";
    print "  -w do not emit warnings about missing variables.\n";
    print "\n";
    print "  When the converted_file argument is missing, STDOUT is used.\n";
    print "  When the setext_file argument is missing, STDIN is used.\n";
    print "\n";
    print "  To get conditional text within a setext document to be displayed,\n";
    print "  supply a definition tag through the -c option. For example,\n";
    print "\n";
    print "          $pgm -c NEDITDOC help.etx nedit.doc\n";
    print "\n";
    print "  would generate a plain text document, nedit.doc, from the source\n";
    print "  help.etx, including/excluding text marked with 'NEDITDOC'\n";
    print "  conditional text markers, also known as 'maybe' typotags.\n";
    print "\n";

    exit 0;
}

#---------------------------------------------------------------------------
# This is a GetOptions call back function for gleaning variables from
# the command line so that they can be available to the setext parsing
# without having to appear in the setext document. The expected form
# on the command line is: -v variableName=value. For example, -v version=5.2
#---------------------------------------------------------------------------
sub declare_variable
{
    my $optionName  = shift;
    my $optionValue = shift;
    my ( $varName, $varValue ) = split( "=", $optionValue );
    
    $varValue or do { 
       print STDERR "Missing value for variable '$varName'\n"; 
       $Getopt::Long::error++; 
       return 
       };
    
    #-----------------------------------------------------
    # By trimming off leading and trailing spaces allows
    # data entry like this: "version = 5.2 of Oct. 2001".
    #-----------------------------------------------------
    $varName  =~ s/$trim_spaces/$2/o;
    $varValue =~ s/$trim_spaces/$2/o;
    
    $variables{ $varName } = $varValue;
}

#-------------------------------------------------------------------------------

sub emit_setext_definition
{
    print <<END_OF_DEFINITION_TEXT;

Typotags Available
------------------

 The following table contains typotags recognized by
 $pgm. The "setext form" column in the table
 is formatted such that the left most character of
 the column represents the first character in a line
 of setext. The circumflex character (^) means that
 the characters of the typotag are significant only
 when they are anchored to the front of the setext
 line. This definition is a sample of a setext document.
 Consequently, it must be put through the program so
 that you can view the actual "setext form" of some
 of the typotags. Thus, issue the following commands
 to get a proper text view of the table below.
 
     $pgm -T > typotags.etx
     $pgm -w typotags.etx

 ============  ===================  ==================
!     name of  setext form          acted upon or
! the typotag  of typotag           displayed as
!============  ===================  ==================
!    title-tt "Title                a title
!              ====="               in chosen style
!------------  -------------------  ------------------
!  subhead-tt "Subhead              a subhead
!              -------"             in chosen style
!------------  -------------------  ------------------
!  section-tt ^#> section-text      a section heading
!                                   with '#' from 1..9
!                                   in chosen style
!------------  -------------------  ------------------
!   indent-tt ^  lines indented     lines undented
!             ^  by 2 spaces        and unfolded
!------------  -------------------  ------------------
!     bold-tt      **[multi]word**  1+ bold word(s)
!   italic-tt         ~multi word~  1+ italic word(s)
!underline-tt       [_multi]_word_  underlined text
!      hot-tt        [multi_]word_  1+ hot word(s)
!    quote-tt ^>[space][text]       > [mono-spaced]
!   bullet-tt ^*[space][text]       [bullet] [text]
!  untouch-tt  `_quoted typotag!_`  `_left alone!_`
!  notouch-tt ^!followed by text    text-left-alone
!    field-tt     |>name[=value]<|  value of name
!     line-tt ^   ---               horizontal rule
!------------  -------------------  ------------------
!     list-tt  .([space]list start  multiple line list
!                                   element ends with
!                                   empty line
!  endlist-tt  .)                   denotes list end
!------------  -------------------  ------------------
!     href-tt ^.. \@_word URL         jump to address
!     note-tt ^.. \@_word Note:("*")  ("cause error")
!   target-tt     \@_[multi_]word     [multi ]word
!------------  -------------------  ------------------
!  twobuck-tt  \$\$ [last on a line]  [parse another]
! suppress-tt ^..[space][not dot]   [line hidden]
!   twodot-tt ^..[alone on a line]  [taken note of]
!------------  -------------------  ------------------
!    maybe-tt ^.. ? name[~] text    show text when
!                                   name defined
! maybenot-tt ^.. ! name[~] text    show text when
!                                   name NOT defined
! endmaybe-tt ^.. ~ name            end of a multi-
!                                   line maybe[not]-tt 
!------------  -------------------  ------------------
! passthru-tt ^!![text]             text emitted
!                                   without processing
!------------  -------------------  ------------------
!   escape-tt  @\@x where 'x'  is     x is what remains
!              escaped character    @@@@ needed for 1 @@
 ============  ===================  ==================

 Only one instance of the element subhead-tt (or, in its
 absence, title-tt) is absolutely _required_ for a text to
 be considered a valid setext.

 All the elements, but subhead-tt, are in effect optional,
 that is, not necessary for a setext to be declared as
 such. The target-tt element allows the hypertext link
 definition of href-tt to be within the same setext. The
 actual reference (href-tt) of the target would look like:

    .. _word #reference_within_document

!Multiple line maybe[not]-tt (conditional text regions)
!are introduced as ".. ? name~" or ".. ! name~" and are
!terminated with ".. ~ name", on a separate line. Single
!line maybe[not]-tt do not use the '~' character and are
!terminated with the end of the line. The special
!conditional text region named "html" allows a mixture of
!setext and HTML tags. Nesting of these typotags is
!allowed. For instance, if there are three conditional
!regions, A, B, and C, C can be nested inside B, which can
!be nested inside A (eg. A-B-C...C-B-A). Note that a
!surrounding region cannot end before one of its inner
!regions is terminated (eg. of illegal nesting
!A-B-C...C-A-B, where A terminated prior to B.

 Multiple line list-tt are introduced as ".(". Each line
 belongs to the current list element until an empty line
 is encountered. Once a list-tt is encountered, line
 separated paragraphs constitute list elements.  A list-tt
 is terminated by endlist-tt. The list-tt/endlist-tt
 typotags are allowed to be nested (unlike the bullet-tt).
 These typo-tags do not have to start in the first column
 of a line, but must have leading whitespace if they are
 indented at all.

 Field typotags are used to define and reference values.
 Field definitions can only occur within a suppress-tt.
 For example:  "..  `|>author=Steven Haehn<|`"
 Field references (eg. |>author<|) can occur in any 
 printable text. If there is no known value for the 
 field, it will remain unchanged and appear as written
 in the setext.
END_OF_DEFINITION_TEXT

    #---------------------------------------------------------------
    # Emit any predefined variables so user knows what is available.
    #---------------------------------------------------------------
    if( %variables )
    {
        print "\n";
        print " The following are predefined for use in a field-tt\n";
        print " for any setext document translated by this utility.\n";
        print "\n";
        
        foreach $key ( sort keys %variables )
        {
            print "    $key = $variables{$key}\n";
        }
    }
    
    print "\n \$\$\n";
    exit 0;
}

#-------------------------------------------------------------------------------

$pgm = basename( $PROGRAM_NAME );

#==========================
# Global shared definitions
#==========================
$um          = "\375"; # untouchable marker
$vm          = "\374"; # variable marker
$escMrk      = "\33";  # internal escape marker
$trim_spaces = '(\s*)(.*?)(\s*)$';
$list_level  = 0;
$listIndent  = 2;
@bullet_list = qw( * * o + * o + * o + );
%variables   = ( date => &date(), Date => &date("D"), year => &date("y") );
@cond_text_definitions = ();
$make_title_href = 1;

#---------------------------------------
# Variables needed for HTML conversions.
#---------------------------------------
$lt      = "\376"; # "<" marker
$gt      = "\377"; # ">" marker
$amp     = "\373"; # "&" marker
$htmlExt = "html"; # default HTML file name extension

$htmlHeader =
     "<HTML>\n<HEAD>\n" .
     "<TITLE>\$HTML_TITLE</TITLE>\n" .
     "</HEAD>\n" .
     "<BODY>\n";
     
$htmlFooter = "</BODY>\n</HTML>\n";

#---------------------------------------------------------
# Look for following options, complain about unknown ones.
#---------------------------------------------------------