setext-info.txt

nedit 是一款linux下的开发源码的功能强大的编辑器

  What is setext
----------------

  The following is extracted from text written by Ian Feldman.
  
  As originally explained in TidBITS#100 and mentioned there from 
  now on, that publication now comes "wrapped as a setext." The noun
  itself stands for both a method to wrap (format) texts according 
  to specific layout rules and for a single _structure_enhanced_
  text.  The latter is a text which has been formatted in such a
  fashion that it contains clues as to the typographical and logical
  structure of its source (word-processed) document(s), if any.
  Those clues, which are called "typotags," facilitate later automatic
  detection of that structure so it can be validated, extracted,
  processed, transformed, enhanced as needed, if needed.

  It follows that setexts, being nothing but pure text (albeit with a
  special layout), are eminently readable using ANY editor or word
  processor in existence today or tommorrow, on any computer with a
  computer program that is capable of opening and reading text files. 
  By default all properly setext-ized files will have an ".etx" or
  ".ETX" suffix.  This stands for an "emailable/ enhanced text", the
  ExtraTerrestrial overtones nothwistanding ;-))

  Unlike other forms of text encoding that use explicit, visible tag
  elements such as <this> and <\that>, the setext format relies
  solely on the presence of _implicit_ typotags, carefully chosen
  to be as visually unobtrusive as possible.  The underlined word
  above is one such instance of the defacto "invisible" coding. 
  Inserted typotags will at worst appear as mere "typos" in the text.

  [Extensions made to the original set of typotags have muddied this
  clarity a little bit, but they were necessary for NEdit development.]

  Similarly, just to give an example, here is a short description
  of the four types of word emphasis typotags that setexts MAY
  contain, limited to one emphasis type ONLY per word or word group:

 -------------------  ----------------------------  --------------
!      **aBoldWord**  **multiple bold words**       ; bold-tt
!_anUnderlinedWord_    _multiple_underlined_words_  ; underline-tt
!    ~anItalicWord~    ~multiple italicized words~  ; italic-tt
!         aHotWord_     multiple_hot_words_         ; hot-tt 
 ----------------------------------------------------------------- 

 What makes a setext?
---------------------

  Before any decoding can take place a text has first to be
  verified whether it is a setext and not some arbitrarily-wrapped
  stream of characters.  Although there are more ways than one to
  achieve that goal there is one _primary_ test that has to be
  passed with colors or else the text being tested cannot be a
  setext. 

  Chief among the typotags are two that signal presence of setext
  titles and subheads inside the text.  A setext document can be
  formatted more or less properly, may contain or lack any other of
  its "native" elements but it has to have at least one proper
  subhead or a title in order to be declared as "a certified
  setext."

    Column 1 of text line
    |
    V
    Here are a few demo setext subheads:     
    ------------------------------------

    _ _ _ _ Which Share Just One _ _ _ _
    ------------------------------------

            ----------> UnifyinG FeaturE
    ------------------------------------

    of EQUAL RIGHTMOST VISIBLE character 
    ------------------------------------

      length as that of its subhead-tt's    
    ------------------------------------

    [this line is called subhead-string]
    ------------------------------------

    [the one below is called subhead-tt]
    ------------------------------------

    [together they make a valid subhead]
    ------------------------------------

       (!) and of course, subheads do not have to be of the same length ;-)
    -----------------------------------------------------------------------

      (nor have to begin in column 1)    
    ---------------------------------

     although it is recommended that they stay below 40 characters
    --------------------------------------------------------------

        Second Setext In This File
    ==============================

     ((end of examples))
     -------------------
     ((_not_ a subhead))
    ^
    |
    Column 1 of text line

  Note, the last 3 lines of the examples do not constitute a valid
  subhead because they do not start in column 1.

  Chief among the reasons why one should first look for presence of
  subheads rather than titles is that it is fully conceivable that a
  setext might have been created without an explicit title-tt in
  order to allow decoder programs to distinguish between part one
  and any subsequent ones in a possible multi-part mailing. This
  absence of a title-tt could be enough of a signal to start looking
  for possible "part x of y" message in either the subject line,
  filename or anywhere "above" the first detected subhead of the
  current text. 

  Therefore, here's a formal definition of what makes a setext:

 +-------------------------------------------------------------+
 |  a text that contains at least one verified setext subhead  |
 |  or setext title                                            |
 +-------------------------------------------------------------+

 Other considerations
---------------------

  A possibility arises to keep the paragraph text unwrapped, rather
  than folded uniformly at say the 66th character mark.  After all,
  if the setext is primarily to be displayed inside an editor,
  rather than on an 80 character terminal screen, then there is not
  much sense in prior folding of the lines to a specific
  guaranteed-to-fit-on-a-TTY-screen length.  The editor/word
  processor program will fit the unwrapped text to the available
  display area, and might actually prefer to have to deal with
  whole unwrapped paragraphs rather than with otherwise relatively
  short lines. 

  Most text-processing programs with native word-wrap capabilities
  actually consider return-terminated lines to be paragraphs in
  their own right.  Thus, if a setext is not to travel via email
  anyway (because of it being distributed differently or making use
  of accented characters) then it might as well arrive in unfolded
  state so that no extra time need be spent on making the
  paragraphs "whole again." [This is not the choice that is taken
  with NEdit help because it is easier to visualize the final text
  for those who do not use text wrapping.] 
  
  Observe that it is not the state of the paragraph text that makes
  or breaks a setext.  No, the sole criterion of whether a text is
  a setext is the presence of at least one verified subhead, as
  described above. Thus even texts with unfolded paragraphs are
  setexts if they contain at least one subhead-tt.

  The sole mechanism used in setext to encode which of such lines
  are in reality paragraphs (as opposed to those that shouldn't be
  folded mechanically) is the character indent.  In fact, after the
  subhead-tt the second most important typotag is the indent-tt,
  made up of exactly two space characters, which denotes any such
  indented lines as ready-candidates for reflowing by so inclined
  front-ends (either on their own or as part of like-indented lines
  above and below it).  So any potentially long line of a setext
  that has been indent-tted will be understood (by any validated
  setext front-end) as to be ready for wrapping-to-length if so
  required. 

.. All the following document by Steven Haehn

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

  The following table contains typotags recognized by the setext
  utility. 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. Typotags marked
  with an asterisk (*) are extensions added for NEdit help
  generation.

!! ============   ===================  ==================
!!      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
!! ------------   -------------------  ------------------
!!      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 @
!! ============   ===================  ==================
!!

  The title-tt, subhead-tt and indent-tt have already been