home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 13 / AACD13.ISO / AACD / Resources / System / BoingBag1 / Internet / AWeb / Plugins / HTTX / HTTX.doc.eng < prev    next >
Text File  |  1999-12-20  |  38KB  |  1,074 lines
  1.                                     HTTX
  2.  
  3.                            HTML to TEXT converter
  4.                          Created by Gabriele Favrin
  5.                (E-Mail: favrin@tin.it - FidoNet: 2:333/726.8)
  6.  
  7.                         Version 2.0b - December 1999
  8.  
  9.  
  10.  
  11. Index:
  12.  
  13.   1. Utilization terms
  14.   2. Property of HTTX and distribution terms
  15.   3. Introduction
  16.   4. Hardware requirements and installation
  17.   5. How to use
  18.      5.1 Command line parameters
  19.      5.2 External configuration
  20.   6. Error Messages and AmigaDOS Return Codes
  21.   7. FAQ (advices, interfacing with other programs and more)
  22.   8. Technical informations
  23.      8.1 What is supported, what is not (yet) and implementation
  24.      8.2 Notes about ANSI conversion
  25.      8.3 Notes about conversion of <PRE>, <XMP>, <LISTING> and <SCRIPT>
  26.          contents
  27.   9. How to contact the Author
  28.  10. Greetings
  29.  11. Program history
  30.  12. Future versions
  31.  
  32.  
  33.  
  34. -----------------------------------------------------------------------------
  35.  
  36.                               *** CHILDWARE ***
  37.  
  38. This  software  is  "CHILDWARE". The author explicitly asks whoever uses this
  39. program  to  make  a  donation toward a beneficial corporate body which works
  40. helping children in some way.
  41.  
  42. If  you  don't know of any, ask at your local post office and inform yourself
  43. on how to make a donation to UNICEF.
  44.  
  45. The amount of the offer is up to you, but please do it!
  46.  
  47. -----------------------------------------------------------------------------
  48.  
  49.  
  50.  
  51. 1. Utilization terms
  52. --------------------
  53.  
  54. Before  running  this  program  on  your  computer, please read carefully the
  55. following  paragraph,  and  continue only if you agree with the terms written
  56. below.
  57.  
  58. THE  HTTX  AUTHOR  IS IN NO WAY RESPONSIBLE FOR MORAL AND/OR MATERIAL DAMAGES
  59. THAT  HIS PROGRAM MAY CAUSE TO PEOPLE OR THINGS. THE PROGRAMMER GAVE HIS BEST
  60. TO  LIMIT  THE  PROBLEMS THAT HTTX MAY CAUSE, BUT HE IS NOT ABLE TO GUARANTEE
  61. ITS  EFFICIENCY  IN  ALL  THE  SITUATIONS.  USING  HTTX,  YOU,  THE USER, ARE
  62. RESPONSIBLE FOR ALL MORAL, MATERIAL, CIVIL AND PENAL THINGS.
  63.  
  64.  
  65. WARNING:
  66.  
  67. Many HTML documents are under Copyright, and are not freely distributed, even
  68. if  converted  to plain text format. The author declines every responsibility
  69. in the utilization of the files generated with HTTX.
  70.  
  71. All  of  the  programs  mentioned  in  this  document are properties of their
  72. respective owners.
  73.  
  74.  
  75.  
  76. 2. Property of HTTX and distribution terms
  77. ------------------------------------------
  78.  
  79. The executable program, the source code and the ideas that are its basis are
  80. the EXCLUSIVE PROPERTY of Gabriele Favrin. All rights reserved.
  81.  
  82. HTTX is freeware, NOT public domain. It may be spread only if the executable
  83. files and the documentation remain unchanged. Distribute of the files in
  84. archive formats other from LhA is permitted, but compressing the individual
  85. files using PowerPacker or similar tools is not.
  86.  
  87. Commercial use of this package is exclusively granted to AmiTrix who may
  88. spread it with complete or partial versions of the AWeb WWW Browser.
  89.  
  90. Staffs of Aminet, Fred Fish, Meeting Pearls, Amy Resource and Amiga magazines
  91. which have a cover CD disk are authorized to include HTTX in their public
  92. domain software collections.
  93.  
  94.  
  95.  
  96. 3. Introduction
  97. ---------------
  98.  
  99. HTTX (HTml > TXt) is a program to convert files from HTML format, used for
  100. viewing files on World Wide Web, to pure ASCII. There are analogous products,
  101. but since none had completely satisfied my needs, I started to write one
  102. myself.
  103.  
  104. I don't say this is the best or the fastest one, but surely it has some
  105. functions unpublished in similar Amiga programs till now.
  106.  
  107.  
  108.  
  109. 4. Hardware requirements and installation
  110. -----------------------------------------
  111.  
  112. Required system:
  113. Amiga, 512K, Kickstart 2.04 (37.175) or above.
  114.  
  115. Required memory:
  116. The size of the file to convert to, and about a 15K, for buffers and other.
  117.  
  118. Install:
  119. Copy HTTX to your C: directory or a directory in your current path.
  120.  
  121. HTTX is compatible with AmigaOS 3.5 and U.A.E.
  122.  
  123.  
  124.  
  125. 5. How to use HTTX
  126. ------------------
  127.  
  128. HTTX can be only used from Shell. Users of AWeb please note that a special
  129. ARexx plugin to fully control HTTX from the browser is included in this
  130. distribution. Also please read section 7.
  131.  
  132. Command syntax:
  133.  
  134. HTTX InputFile [OutputFile] [options]
  135.  
  136. The parameters in square brackets are optional. You are only required to
  137. specify a valid HTML file ("InputFile").
  138.  
  139. If there is no OutputFile specified, it defaults to 'InputFile'.txt (eg.
  140. "test.html" will be saved as "test.txt"). If a path is specified for
  141. OutputFile, that file will be saved to that path.
  142.  
  143. Examples:
  144.  
  145. -> HTTX data:txt/html/abox.html
  146.  
  147. The file "aboxe.html" will be converted and saved
  148. as "data:txt/html/abox.txt"
  149.  
  150. -> HTTX data:txt/html/aboxe.html ram:aboxe.txt
  151.  
  152. The file "abox.html" will be converted and saved
  153. as "ram:abox.txt"
  154.  
  155. -> HTTX data:txt/html/abox.html data:txt/
  156.  
  157. The file "abox.html" will be converted and saved
  158. as "data:txt/abox.txt"
  159.  
  160.  
  161.  
  162. 5.1 Command line parameters
  163. ---------------------------
  164.  
  165. HTTX offers many options to control the conversion process.
  166.  
  167.  
  168. LEN
  169.    Maximum line length of the output file.
  170.  
  171.    Default: 77 - Minimum: 15 - Maximum: 255
  172.  
  173.  
  174. INDENT or IN
  175.    Number of spaces for indentation (re-enter to the right) of the <UL>, <OL>
  176.    and <DL> lists. The specified value must allow at least two levels of
  177.    indentation regarding of the line length specified with the LEN option.
  178.  
  179.    Default: 3 - Minimum: 1 - Maximum: (LEN value - 10) / 3
  180.  
  181.  
  182. ANSIMODE
  183.    ANSI conversion of HTML styles and LINKS (HREF and NAME) and optimization
  184.    of alignment functions.
  185.  
  186.    Not to be used if the converted text will go on message areas, like
  187.    Fidonet or Usenet newsgroups.
  188.  
  189.    Please read the section 8.2 (ANSI conversion) for important
  190.    informations about ANSI sequences and general compatibility issues.
  191.  
  192.    The option supports three modes:
  193.  
  194.    ANSIMODE=0
  195.       No ANSI codes are used. This equals to not place the option both in the
  196.       command line or in the configuration.
  197.  
  198.    ANSIMODE=1
  199.       Standard ANSI codes are used. This is the only ANSI conversion type
  200.       available while printing.
  201.  
  202.    ANSIMODE=2
  203.       VT100 cursor control sequences are used to reduce size of the file by
  204.       compressing spaces. This could cause incompatibility with some programs
  205.       (see section 8.2).
  206.  
  207.    Default: ANSIMODE=0 (styles are not converted).
  208.  
  209.  
  210. ANSICOL
  211.    Color used to render the links during ANSI conversion.
  212.    Accepted value range is from 0 to 9. The colour shown may depend from the
  213.    terminal program used.
  214.  
  215.    Default: 3 (file save) or 4 (printing).
  216.  
  217.  
  218. 7BIT
  219.    Conversion of HTML entities (accent letters, symbols, and so...) to ASCII
  220.    codes lower than 128. This is required for text forwarded on nets like
  221.    FidoNet, where the character codes allowed can only range between
  222.    32 and 127.
  223.  
  224.    IMPORTANT: remember that the ANSI option adds Escape codes (ASCII 27),
  225.    forbidden on FidoNet, and strongly not recommended for a non personal use
  226.    (broadcast) of converted text.
  227.  
  228.    Default: OFF (8 bit chars are not converted).
  229.  
  230.  
  231. HRMODE or HR
  232.    HTML documents often contains the <HR> TAG, which defines a separating
  233.    line between paragraphs. HTTX allow the management of these lines in
  234.    three ways:
  235.  
  236.    HRMODE=0
  237.       No lines drawn.
  238.       It was NOHR in HTTX versions before 1.5.
  239.  
  240.    HRMODE=1
  241.       Lines are drawn using the minus "-" character.
  242.  
  243.    HRMODE=2
  244.       Lines are drawn using underlined spaces (in ANSI). This mode
  245.       generates a nicer line, but introduces ANSI codes, it is absolutely to
  246.       be avoided if the text will go on FidoNet or Usenet newsgroups.
  247.  
  248.    Default: HRMODE=1 (lines are inserted using the minus "-" character).
  249.  
  250.  
  251. NOALIGN or NA
  252.    HTTX supports (right or center) alignments of texts and separators (<HR>).
  253.  
  254.    Examples:
  255.  
  256.                                 centered text
  257.                                                            right-aligned text
  258.  
  259.    If NOALIGN option is ON, both the above lines will start on left margin,
  260.    this saves characters.
  261.  
  262.    Default: OFF (alignment is rightly converted).
  263.  
  264.  
  265. TDEOL
  266.    Insertion of an EOL between cells of an HTML table. Using this option
  267.    can improve the layout of some tables.
  268.  
  269.    Default: OFF (between each cell a space is inserted)
  270.  
  271.  
  272. SETNOTE or SN
  273.    Use the document title (<TITLE> TAG) or its url as output file
  274.    comment. This option is ignored when options PRINT or STDIO
  275.    (display on console) are used.
  276.  
  277.    The options supports the following values:
  278.  
  279.    SETNOTE=0
  280.       No comment is added.
  281.  
  282.    SETNOTE=1
  283.       Title of the document, if one, is added as comment of the output file.
  284.       Only first 64 characters are saves, as HTML standard defines.
  285.  
  286.    SETNOTE=2
  287.       URL of the document, if available, is added as comment of the output
  288.       file.
  289.  
  290.    Default: OFF (file comment is not set).
  291.  
  292.  
  293. SITE
  294.    Insertion of the specified source URL in the output file.
  295.    It may be useful to know which document the file was created from.
  296.  
  297.    Example:
  298.    HTTX ram:children.html SITE=http://www.unicef.org
  299.  
  300.    will start the file with "URL  : http://www.unicef.org"
  301.  
  302.    Note: SITE has priority over GETNOTE, so specifying a site this way will
  303.    override that option if it is active.
  304.  
  305.    Default: OFF (without this option the URL will not be added).
  306.  
  307.  
  308. GETNOTE or GN
  309.    Usage of the input file comment as the URL. This option is alternative to
  310.    SITE and is useful with files created using AWeb or other browsers and
  311.    programs which save the URL in the comment.
  312.  
  313.    The AmigaDOS comment length limit is 80 chars.
  314.  
  315.    Default: OFF
  316.  
  317.  
  318. NOHEADER or NOHEAD
  319.    Don't insert HTTX version information, title (<TITLE>) and URL in the
  320.    converted file. This option automatically turns off the SITE and GETNOTE
  321.    options if present.
  322.  
  323.    Default: OFF (HTTX version, optional title and URL may be added).
  324.  
  325.  
  326. HREF or LINK
  327.    Adds the addresses of links (<A> TAG).
  328.    Very useful if the document contains links that you want to keep.
  329.  
  330.    Default: OFF (links aren't added).
  331.  
  332.  
  333. IMG
  334.    Insertion of the ALT-text of images (<IMG> TAG) in the output file.
  335.    Useful if the document contains images with descriptions.
  336.  
  337.    Default: OFF (ALT-text isn't added).
  338.  
  339.  
  340. SCRIPT or SCP
  341.    Insertion of the content of <SCRIPT> TAG, eg. JavaScript, in the output
  342.    file.
  343.  
  344.    Note: this option adds the script itself, not its result!
  345.  
  346.    Please read the section 8.3 for important information about conversion of
  347.    this type of text.
  348.  
  349.    Default: OFF (<SCRIPT> content is skipped).
  350.  
  351.  
  352. BADHTML or BAD
  353.    Partial support for documents created outside of the HTML standards. Use
  354.    this option only if parts of the converted page are missing. Using this
  355.    option with correct HTML documents may cause unpredictable results in the
  356.    converted document.
  357.  
  358.    Default: OFF (HTTX uses standard DTD rules).
  359.  
  360.  
  361. FORCE
  362.    Forces conversion of input file without checking if it is an HTML
  363.    document.
  364.  
  365.    USE IT AT YOUR OWN RISK: conversion of normal text or binary files may
  366.    cause unpredictable results.
  367.  
  368.    Normally, HTTX considers a file valid HTML when one or more of the
  369.    following conditions is valid:
  370.  
  371.    - file extension is .html or .htm
  372.    - the starting TAG is <HTML>
  373.    - the starting TAG is <!DOCTYPE ...>
  374.  
  375.    This option must be specified if the three above conditions are false,
  376.    even if the file IS an HTML document.
  377.  
  378.    Default: OFF (automatic check of file).
  379.  
  380.  
  381. STDIO
  382.    Display the converted file on screen instead of saving it on disk. This
  383.    option automatically enables the QUIET option.
  384.  
  385.    Default: OFF (converted file is saved to disk).
  386.  
  387.  
  388. PRINT or PRT
  389.    Print the document instead of displaying or saving it.
  390.  
  391.    The printer.device will convert standard ANSI codes and end-of-lines to
  392.    the ones used by the Printer set in your Preferences.
  393.  
  394.    This option should be used if you want to print the converted document.
  395.    If ANSIMODE is enabled (value different than 0) it will be set to 1 for
  396.    use of standard ANSI codes. Also, if not specified, value of option
  397.    ANSICOL will be set to 4 (blue color, as from Commodore specifications
  398.    regarding the printer.device).
  399.  
  400.    Older versions of HTTX used a solution like "HTTX abox.html prt:",
  401.    which is now to avoid.
  402.  
  403.    This option automatically enables QUIET, and turns off FILENOTE and STDIO
  404.    options.
  405.  
  406.    Default: OFF (document is displayed on screen or saved to a file).
  407.  
  408.  
  409. APPEND
  410.    Normally HTTX will overwrite an existing file.
  411.  
  412.    If APPEND is ON, the converted text will be added to the end of the
  413.    specified file.
  414.  
  415.    Default: OFF (overwrite output file if it already exists).
  416.  
  417.  
  418. NOCFG
  419.    HTTX loads a default configuration from ENV:httx.prefs (if another is not
  420.    specified with the CFG option). If this option is ON, HTTX uses the
  421.    default values for the options or the parameters specified in the command.
  422.  
  423.    For more informations on external configuration, see section 5.2.
  424.  
  425.    Default: OFF (HTTX searches for default or specified configuration).
  426.  
  427.  
  428. CFG
  429.    With this option it is possible to specify the name of the configuration
  430.    file to be used by HTTX. This file MUST be located in the ENV: directory.
  431.  
  432.    This option turns NOCFG OFF.
  433.    For more informations on external configuration, see section 5.2.
  434.  
  435.    Default: OFF (HTTX loads the httx.prefs configuration file).
  436.  
  437.  
  438. INCLUDE
  439.    Using this option it is possible to include text at the start
  440.    of each output file, before the converted HTML data.
  441.  
  442.    The included text file is NOT ALTERED IN ANY WAY, no 8 bit character
  443.    conversion, wordwrap, ANSI codes and so on. HTTX will not warn if 8 bit
  444.    characters are included.
  445.  
  446.    Remember this, especially if the converted text will go on message areas,
  447.    like FidoNet or Usenet newsgroups.
  448.  
  449.    Default: OFF (no text file is included in the output file).
  450.  
  451.  
  452. QUIET
  453.    Don't display any HTTX messages. This option is useful when HTTX is used
  454.    within a script.
  455.  
  456.    WARNING: if active this option also hides error messages, but the AmigaDOS
  457.    error codes are always returned.
  458.  
  459.    Default: OFF (HTTX output is displayed).
  460.  
  461.  
  462. If not specified, HTTX uses the default settings.
  463.  
  464. When conversion is finished, if QUIET option is OFF, HTTX will show:
  465.  
  466.  - the size of input and output files.
  467.  - the presence of 8 bit chars and their conversion, if active.
  468.    (relative only to HTML content, not the optional included file).
  469.  - TABs or ASCII chars less than 32 not converted because they are included
  470.    in pre-formatted text.
  471.  - non-standard HTML comments, which may make parts of document invisible.
  472.    If the converted file appears incomplete, try using BADHTML option.
  473.  
  474.  
  475.  
  476. 5.2 External configuration
  477. --------------------------
  478.  
  479. HTTX supports an external configuration, this is a text file that includes
  480. the most used options, so they do not need to be typed every time you use the
  481. program.
  482.  
  483. By default (except when NOCFG option is set, or CFG option with a different
  484. filename) HTTX searches the file "ENV:httx.prefs".
  485.  
  486. It's possible to create multiple configurations, maybe one to use for file
  487. conversion and another one to use for printing, creating different
  488. configuration files and enabling the CFG option with the name of the file (do
  489. not specify the path, it is always 'ENV:').
  490.  
  491. Example:
  492.  
  493. -> HTTX abox.html
  494.  
  495. Converts "abox.html" using default configuration (ENV:httx.prefs).
  496.  
  497. -> HTTX abox.html PRINT CFG=httxprt.prefs
  498.  
  499. Converts "abox.html" using the configuration file ENV:httxprt.prefs
  500.  
  501.  
  502.  
  503. Allowed parameters
  504. ------------------
  505.  
  506. The external configuration file supports a subset of available command line
  507. options. Each option MUST be specified in its extended form (for example
  508. HRMODE, not HR, INDENT instead of IN, and so on).
  509.  
  510. The file must contain only the options and their parameters. It's allowed to
  511. put each option on a separate line for better readability.
  512.  
  513. Available options (for description see section 5.1):
  514.  
  515. LEN      - the maximum length for output lines.
  516. INDENT   - the indentation size.
  517. ANSIMODE - type of ANSI sequences used during conversion.
  518. ANSICOL  - colour used for links during ANSI conversion.
  519. 7BIT     - conversion of 8 bit HTML entities to 7 bit chars.
  520. HRMODE   - line drawing mode.
  521. NOALIGN  - ignore center and right alignment.
  522. TDEOL    - insertion of an EOL between table cells.
  523. SETNOTE  - use HTML document title or URL as the output file comment.
  524. GETNOTE  - use the source file comment as URL of destination file.
  525. NOHEADER - skip header (HTTX version, URL and title of original
  526.            document) in the converted file.
  527. HREF     - insertion of links (<A>) in the destination file.
  528. IMG      - insertion of the ALT-Text of images in the destination file.
  529. SCRIPT   - insertion of the content of <SCRIPT> element in the
  530.            destination file.
  531. BADHTML  - partial support for badly written HTML.
  532.  
  533. Parameters specified on command line acts after the parameters specified in
  534. the configuration file. This can eventually override (or toggle twice) one or
  535. more options.
  536.  
  537. Examples:
  538.  
  539. If a configuration file has the following line:
  540.  
  541. IMG GETNOTE LEN=70
  542.  
  543. and on command line you write:
  544.  
  545. -> HTTX abox.html IMG
  546.  
  547. the result is IMG turned on because it's present in configuration file, but
  548. is turned off again because it's also present in command line.
  549.  
  550. -> HTTX abox.html LEN=74
  551.  
  552. LEN is both present in configuration file and command line, but this one
  553. overrides the previous value. LEN is now set to 74.
  554.  
  555.  
  556.  
  557. How to create an external configuration
  558. ---------------------------------------
  559.  
  560. External configuration files are in effect system variables and are located
  561. in ENVARC: directory (on disk) and ENV: (generally on RAM). So, the contents
  562. in ENV: are valid only for the current session, while the contents in ENVARC:
  563. are also valid after a reset.
  564.  
  565. To permanently save a configuration file, copy it both in ENV: and ENVARC:
  566.  
  567. Use your favorite text editor (Ed, Cygnus Editor, GoldEd, and so on) to
  568. create your prefs file, httx.prefs is the default filename. Save it in ENV:,
  569. also save the file to ENVARC: so it will not be lost when you reboot.
  570. Temporary changes can be made by editing just the ENV: file.
  571.  
  572. HTTX configuration may be fully managed using the plugin for the AWeb WWW
  573. browser.
  574.  
  575.  
  576.  
  577. 6. Error Messages and AmigaDOS Return Codes
  578. -------------------------------------------
  579.  
  580. When execution terminates, HTTX returns the appropriate AmigaDOS Return Code
  581. (RC), usable within scripts to determine if the conversion was successful.
  582. See your AmigaDOS handbook for a complete list of error codes.
  583.  
  584. In case of error, if QUIET is off, the appropriate AmigaDOS message will be
  585. displayed.
  586.  
  587. Following is a list of the most common errors. If the system is localized,
  588. messages are displayed in the appropriate language. See your AmigaDOS manual
  589. for further information.
  590.  
  591.  
  592. Argument line invalid or too long
  593.    Arguments entered in a wrong way.
  594.  
  595. *** Break
  596.    The user has pressed Control-C keys, interrupting the conversion, and the
  597.    output file has been removed.
  598.  
  599. Not enough memory available
  600.    There is no memory available to allocate the buffers used by HTTX.
  601.    This can happen if the HTML file to convert or the text file to include
  602.    is too big or the memory is too fragmented.
  603.    Try to rebooting your Amiga.
  604.  
  605. Object not found
  606.    Specified file doesn't exist or it's not accessible.
  607.    Check file name and path.
  608.  
  609. Object is not of the required type
  610.    The input file seems not to be an HTML document.
  611.    Try using the FORCE option.
  612.  
  613.  
  614. HTTX can display other errors (in English only) due to wrong use of commands
  615. or options:
  616.  
  617.  
  618. The line length must be between 15 and 255 characters (current is NN)
  619.    The line size specified with LEN parameter is a number less than 15 or
  620.    more than 255.
  621.  
  622. Indentation size must be at least 1 (current is NN)
  623.    The indentation size must be at least one character.
  624.  
  625. With line length XX, indentation size YY, max indent level is ZZ.
  626. You must allow at least 3 indentations.
  627.    The maximum indentation level, with specified line size and indent value,
  628.    is less than 3.
  629.  
  630. HRMODE value must be 0, 1 or 2
  631.    Value set for HRMODE is not valid. It must be 0, 1 or 2.
  632.  
  633.  
  634. Finally, there are a few warnings which may be displayed. The conversion will
  635. take place but there may be situations altering the final result:
  636.  
  637.  
  638. Error in env config. HTTX will use its defaults.
  639.    External configuration file has errors. HTTX will use the default settings
  640.    and the parameters passed on the command line.
  641.  
  642.    Check external configuration file (see section 5.2).
  643.  
  644. ENV config 'NAME' not found.
  645.    The configuration file specified with CFG option was not found.
  646.    HTTX will use the default settings and the parameters passed on command
  647.    line.
  648.  
  649.    Remember that the configuration file must be located in ENV:
  650.    Remember also to copy it again to ENVARC: when you edit it.
  651.  
  652. Found non-ASCII chars in preformatted text!
  653.    In a non formatted text section HTTX has found some 8 bit characters.
  654.    Do not ignore this warning if the converted text will be posted in
  655.    Fidonet conferences or Usenet newsgroups.
  656.  
  657. This file contains non standard HTML comment(s)!
  658.    File could be not completely converted, since non standard HTML comments
  659.    were found. If this is the case, try using BADHTML option.
  660.  
  661. Include file could not be added.
  662.    File specified with INCLUDE option can't be added because it doesn't
  663.    exist or it's not accessible.
  664.    Check file name and path.
  665.  
  666.  
  667.  
  668. 7. FAQ (advises, interfacing to other programs and more)
  669. --------------------------------------------------------
  670.  
  671. Q. ANSI styles (bold, italic, underline, blue) stop after first line.
  672. A. See section 8.2.
  673.  
  674. Q. Converted text isn't centered, but in the original document it is.
  675. A. This can happen if the text in a table row (<TR>) or cell (<TD>) is
  676.    defined as centered. To maintain compatibility to some programs used with
  677.    HTTX, this version doesn't yet supports alignment defined in those
  678.    elements. This will be added in future versions that will have more table
  679.    support. Otherwise it may be an ANSI compatibility problem
  680.    (check section 8.2).
  681.  
  682. Q. Sometimes alignment doesn't work, wordwrap and lists are not correctly
  683.    formatted or HTML TAGS are shown.
  684. A. It's the text included in the element <PRE>. HTTX copies this text as is,
  685.    without formatting. This choice was made because often that kind of text
  686.    contains text that the document's author probably wishes to show as is.
  687.  
  688.    In <LISTING> and <XMP> the TAGS are left as they are, as specifications
  689.    for those elements define. Although its use is deprecated in HTML 4.0,
  690.    <XMP> is still largely used for examples in many documents.
  691.    eg. in the Netscape JavaScript specifications.
  692.  
  693. Q. Some pages are not correctly converted...
  694. A. There could be many reasons: layout based on tables (not fully supported,
  695.    see section 8.1), errors on HTML source (HTTX is quite tolerant, but there
  696.    are limits) or errors on HTTX engine. If you think the page is correct,
  697.    send me an E-mail with the URL.
  698.    (E-Mail: favrin@tin.it, FidoNet: 2:333/726.8)
  699.  
  700. Q. Can I use HTTX from other programs?
  701. A. In this archive an ARexx plugin is provided to use HTTX with the AWeb
  702.    browser.
  703.  
  704.    Regarding external programs, HTTX can be easily used from Directory Opus
  705.    by creating a button configured as follow (Directory Opus 4.12):
  706.  
  707.    New Entry/AmigaDOS:
  708.      C:HTTX {f} {d}
  709.      (replace C: with path for HTTX)
  710.  
  711.    With this configuration, a file selected from "source" directory will be
  712.    converted to text and saved to the "destination" directory.
  713.  
  714.    By activating "Do all files" flag it's possible to convert more than one
  715.    file, by selecting them and clicking the HTTX button.
  716.  
  717. Q. Are there GUI for HTTX?
  718. A. Alfonso Ranieri (alfier@iol.it) has written an ARexx script that offers a
  719.    StormWizard interface to configure HTTX.
  720.  
  721.    The AWeb plugin contains a Reaction interface for configuration. A
  722.    separated version to be used from wb will be available soon.
  723.  
  724. Q. I'm using a program that refers to HTTX for printing html (eg. MoreHTML).
  725.    If I install versions newer than HTTX 1.1b the printing doesn't work any
  726.    more.
  727. A. Various programs that use HTTX were written to work with version HTTX
  728.    1.1b. They use a command like "HTTX <filename> prt:" to print the
  729.    converted text. This doesn't work any more, especially if the ANSIMODE
  730.    option is used. HTTX versions 1.5 and newer may use some ANSI codes that
  731.    are not compatible with this printing method.
  732.  
  733.    The solution is to ask author of these programs to change the template
  734.    they use to call HTTX, if it isn't directly configurable by the user.
  735.  
  736. Q. How can I improve the performances of HTTX?
  737. A. To speed up the conversion, try using a filesystem with blocks of 1024
  738.    bytes, like RAM disk. Note that if memory is almost full or fragmented,
  739.    saving to RAM disk may slow down the conversion process.
  740.  
  741. Q. Can I make HTTX resident?
  742. A. Starting from version 2.0 HTTX "should" be resident-able. Anyway it hasn't
  743.    been possible to fully test its behavior in this state, so, to avoid
  744.    problems to users, this option is not officially supported.
  745.  
  746.    Whoever wants to try can type the following command in a shell:
  747.  
  748.    Resident C:HTTX FORCE
  749.    (replace C: with path for HTTX)
  750.  
  751.  
  752.  
  753. 8. Technical informations
  754. -------------------------
  755.  
  756. This section talks about some thematics of HTML and its implementation in
  757. HTTX. Although reading this is not required to learn how to use HTTX, there
  758. is important information about conversion that you should read if you plan to
  759. distribute your converted texts.
  760.  
  761.  
  762.  
  763. 8.1 What is supported, what is not (yet) and implementation
  764. -----------------------------------------------------------
  765.  
  766. Supported HTML:
  767.  
  768.  - Entities described in RFC 1866, © and ® (NHTML), numeric entities
  769.    (both decimal and hex), Win'95 numeric entities and special characters.
  770.  - Separators (<CENTER>, <DIV>, <BR>, <P>, <HR>) and font height change
  771.    (from <H1> to <H6>).
  772.  - Alignment (center and right) of text (headers and paragraphs) and
  773.    separators.
  774.  - Physical and logical styles.
  775.  - Numbered lists (<OL> with possible START attribute) of numeric,
  776.    alphabetical and mixed type, unnumbered (<UL>) and definition (<DL>) lists
  777.    to a maximum of 255 levels.
  778.  - Document title (<TITLE>).
  779.  - Links (<A>), user maps and inline images (<IMG> with optional
  780.    ALT-text).
  781.  - Pre-formatted text (<PRE>, <XMP> and <LISTING>).
  782.  - Scripts (content of the<SCRIPT> TAG).
  783.  - Non standard use of "<" and ">" in a preformatted text (this may be
  784.    changed).
  785.  
  786. What is (not yet fully) supported:
  787.  
  788.  - Tables (<TABLE>). Currently each table cell is treated as a separate
  789.    document with its alignment, list indentation level, styles and so on.
  790.  - <APPLET>, <STYLE> and <SELECT>: content of these elements is skipped.
  791.  
  792. Implementation of the standard:
  793.  
  794.  - Unknown TAGS are ignored.
  795.  - Double spaces, trailing and leading blanks for each line are removed.
  796.  - Unprintable ASCII chars (lower than 32) are converted to spaces.
  797.  - PC end-of-lines (CR+LF) and MAC (CR) are converted to Amiga format (LF).
  798.  - For better readability of text in tables, <TD> is converted to a space and
  799.    <TR> TAGS are converted to EOL. Between two <TR> (a table row) a
  800.    maximum of one separator (<HR>) is shown.
  801.  - Consecutive EOLs are reduced to one EOL (except for <BR>).
  802.  
  803. These rules are followed except in <SCRIPT>, <PRE>, <LISTING> and <XMP>
  804. elements). See section 8.3 for more informations about this.
  805.  
  806.  
  807.  
  808. 8.2 Notes about ANSI conversion
  809. -------------------------------
  810.  
  811. If ANSI option is enabled (values 1 or 2) HTTX uses ANSI escape sequences for
  812. converting HTML styles (such as bold, italic, underlined and so on...), links
  813. (rendered as underlined blue), centering and indentation of text.
  814.  
  815. The ANSI codes used are taken from standard ANSI specifications and should be
  816. supported by any program (should be...).
  817.  
  818. These are the sequences (ESC is replaced by "\e"):
  819.  
  820. Bold         \e[1m
  821. Italic       \e[3m
  822. Underlined   \e[4m
  823. Color (Blue) \e[33m (\e[34m with the PRINT option)
  824.  
  825. Multiple ANSI definition is done using the ";", ie. to set bold and italic
  826. HTTX uses "\e[1;3m".
  827.  
  828. If ANSIMODE option gets value 2, for list indentation and text alignment,
  829. HTTX uses the cursor position sequence "\e[nnC" where nn is the number of
  830. characters to move right. This sequence is not used when printing.
  831.  
  832.  
  833. Compatibility problems:
  834.  
  835. - ANSI standard says that the end of line doesn't cause a style to stop, so
  836.   if a style is terminated after first line the problem is in the program
  837.   used to display text. Standard shell and MultiView works correctly.
  838.  
  839. - Some text viewers (like Multiview) don't support VT100 cursor positioning
  840.   sequences that are used when ANSIMODE=2 (optimized ANSI) is enabled. If a
  841.   page contains lists or aligned text that appears badly converted, try to
  842.   convert it using ANSIMODE=1 option or use a different text viewer.
  843.  
  844.  
  845.  
  846. 8.3 Notes about conversion of <PRE>, <XMP>, <LISTING> and <SCRIPT> contents
  847. ---------------------------------------------------------------------------
  848.  
  849. Rules specified for implementation of the standard (section 8.1) wordwrap of
  850. text and 7 bit conversion of 8 bit characters aren't totally valid for some
  851. elements. The HTML specifications require them to be treated differently.
  852.  
  853. - <PRE> element (preformatted text)
  854.   In this mode wordwrap is not done. Parsing of HTML TAGS (except lists and
  855.   alignment) and entities is done. Numeric entities lower than 32 aren't
  856.   converted to avoid problems with uuencoded files contained in HTML pages.
  857.  
  858. - <XMP>, <LISTING> and <SCRIPT> elements.
  859.   The contents of these elements are left unchanged. No wordwrap, entities
  860.   conversion, or TAGS parsing is done at all. If the 7BIT option is used,
  861.   ASCII characters lower than 32 are converted to spaces. ASCII characters
  862.   higher than 128 are left as they are and Win'95 entities are not remapped.
  863.   Remember this, if the converted text will go on message areas, like Fidonet
  864.   or Usenet newsgroups!
  865.  
  866.  
  867.  
  868. 9. How to contact the Author
  869. ----------------------------
  870.  
  871. Beyond every communication, problem, bug report, advise or other things, a
  872. comment about HTTX will be appreciated, and information of actions toward
  873. corporations who takes care of children (see CHILDWARE).
  874.  
  875. E-Mail : favrin@tin.it
  876. FidoNet: 2:333/726.8
  877.  
  878. Please write me in italian or english, thank you.
  879.  
  880. HTTX support page:
  881. http://www.freeweb.org/varie/poing/soft/httx/index.html
  882.  
  883.  
  884.  
  885. 10. Greetings
  886. -------------
  887.  
  888. Beta testing:
  889.  
  890. William Parker        bill@amitrix.com
  891. Giuseppe Pasanisi     amicus@net-service.net
  892. Neil Bothwick         aweb@wirenet.co.uk
  893. Marco L. Buschini     shido@mclink.it
  894. Claudio Mazzuco       kirk@maya.dei.unipd.it
  895. Giuseppe Ammendolia   ryuga@freenet.hut.fi
  896.  
  897. English documentation and spell check:
  898.  
  899. Fabio Belli           zak@anturio.com
  900. William Parker        bill@amitrix.com
  901.  
  902. Beta testing of AWeb Plugin:
  903.  
  904. William Parker        bill@amitrix.com
  905. Neil Bothwick         aweb@wirenet.co.uk
  906. Dale Currie           dalec@zorro.amitrix.com
  907.  
  908. Special thanks:
  909.  
  910. To Yvon Rozijn for having wanted HTTX inside AWeb II and for all the help he
  911. gives me!
  912.  
  913. To Bill Parker for all the help, his suggestions and his friendship.
  914.  
  915. To Wouter van Oortmerssen for the splendid AmigaE and to Tomasz Wiszkowski
  916. for its evolution, CreativE.
  917.  
  918. To Enrico Altavilla for his programming hints.
  919.  
  920. To the italian music group Pooh (http://www.pooh.it) for the emotions they
  921. gived me for years with their music. Maybe HTTX is born thanks to them too...
  922.  
  923. Finally special thanks to those who wrote me about HTTX and to those who use
  924. it!
  925.  
  926.  
  927.  
  928. 11. Program history
  929. -------------------
  930.  
  931. V2.0b (December 1999)
  932.   -Fixed a bug that could cause insertion of incomplete ANSI codes
  933.    in standard ANSI conversion.
  934.   +Made the source compatible with the new CreativE compiler.
  935.  
  936. V2.0  (September 1999)
  937.   +Reorganized in a modular way the HTML parser, now faster and more
  938.    expandable.
  939.   +Style HTML tags are now recognized only when ANSI conversion is enable,
  940.    thus making non ANSI conversion a bit faster.
  941.   +Enlarged the file writing buffer. This makes HTTX faster on fast devices
  942.    (such as RAM or SCSI HDs) but slower on slow ones (like Zip drives).
  943.   +Added full support for alphabetical and mixed (numeric/alphabetical)
  944.    lists.
  945.   +Added options ANSIMODE (choice of the used ANSI mode), ANSICOL (colour of
  946.    the links), TDEOL (insertion of an EOL between the cells of a table) and
  947.    SETNOTE (type of the file note added to the saved file).
  948.   +Reorganized the display of current settings.
  949.   +Content of the <SELECT> element is now skipped.
  950.   +If ANSI conversion is enabled, content of the <TH> element is now rendered
  951.    in bold.
  952.   +Added an easter egg ;-)
  953.   -Fixed (hopefully) all the wordwrap bugs and their side effects, such as
  954.    duplication of part of the text, bad line length sizing, and so on...
  955.   -If SCRIPT option was enabled a bad output file length could have been
  956.    showed.
  957.   -After an ANSI reset, with underlined text (<U> HTML element), text could
  958.    have been showed in underlined blue.
  959.   -Improved ANSI compatibility while printing: now starting spaces are always
  960.    preceded by an ANSI reset sequence.
  961.   -The settings showed when no argument was given are bad.
  962.   -Error 'ENV config 'NAME' not found.' could have been showed even with
  963.    options QUIET or STDIO.
  964.   -Each cell in a table could contain only one <HR>.
  965.   -FILENOTE option disabled insertion of URL and TITLE of the document even
  966.    when NOHEADER option wasn't used.
  967.   -When printing, links was showed in yellow.
  968.  
  969. V1.7a (June 1998)
  970.   +Added alias PRT for PRINT.
  971.   -Fixed a dangerous bug that could cause HTTX to crash when a (too) long
  972.    line was aligned.
  973.   -Fixed an error in wordwrap that caused layout problems after some lines.
  974.  
  975. V1.7  (January 1998)
  976.   +Rewritten in clearer way various important parts of the source code like
  977.    wordwrap and ANSI management.
  978.   +Made HTML parser more SGML compliant.
  979.   +Improved table support by managing each table cell as a separate document.
  980.   +Added support for hex numeric entities (&#xnn) up to 255 and Win'95
  981.    numeric entities and special characters in the range 128-159.
  982.   +Added support for <SELECT>, <XMP> and improved <LISTING> one.
  983.   +Now text into a <BLOCKQUOTE> (or <BQ>) element is indented.
  984.   +In <PRE> mode numeric entities (&#nn) lower than 32 are left as they are.
  985.   +Added options SCRIPT and INCLUDE.
  986.   +Now when option NOHEADER is used the HTTX version string is not added.
  987.   +Improved support for bad HTML coding.
  988.   +And many other things!
  989.   -Fixed various little aesthetical bugs and bugs related to bad HTML coding
  990.    in documents.
  991.   -Fixed many little problems with old wordwrap (the more relevant was that
  992.    if a line didn't contain spaces and ended with an entity, wordwrap didn't
  993.    work correctly).
  994.   -Numeric entities lower than ASCII 32 weren't converted to spaces.
  995.   -In case of bad arguments, false errors messages were displayed.
  996.   -Last character of file could be skipped in some cases.
  997.   -Various other bugs wiped out!
  998.  
  999. V1.5  (May 1997)
  1000.   +Speeded up very much the program, due to a complete rewrite of HTML parser
  1001.    and optimization of many functions.
  1002.   +Added options HRMODE, NOALIGN, PRINT, APPEND, NOCFG, CFG.
  1003.   +Added alignment support (center and right) of text and separators.
  1004.   +Added support for various TAGS and HTML attributes (like START in numbered
  1005.    lists).
  1006.   +Optimized the ANSI output.
  1007.   +Added support for ANSI separators.
  1008.   +Added support for external configuration.
  1009.   +Improved entities support, now identified, despite of closing character.
  1010.   +More clear HTTX internal error codes. Custom DOS error messages replaced
  1011.    with PrintFault() of AmigaDOS.
  1012.   +Added support for "HTTX source_filename destination_path".
  1013.   +Improved support of separators in tables.
  1014.   +Now HTTX follows with higher fidelity HTML DTD for many TAGS.
  1015.   -Fixed some bugs in wordwrap.
  1016.   -Fixed all signalled bugs in version 1.1b.
  1017.   +... Many many other improvements!!!
  1018.  
  1019. V1.1b (January 1997)
  1020.   -Fixed management of some entities.
  1021.  
  1022. V1.1a (January 1997)
  1023.   -Removed a stupid and rare bug in TAGS management.
  1024.   -Fixed support for MAC EOLs.
  1025.  
  1026. V1.1  (November 1996)
  1027.   +Improved speed.
  1028.   +Added STDIO, QUIET, BADHTML, NOHEADER, GETNOTE options.
  1029.   +Added AmigaDOS return codes support.
  1030.   +Added <ADDRESS> and <LISTING> TAG support.
  1031.   +Modified <BR> and <LI> management, as requested by HTML 3.2 standard.
  1032.   +Rewritten entities management: now they will be converted even if they
  1033.    are not closed with ";".
  1034.   +Extended 7 bit conversion, now faster, more complete (almost all
  1035.    characters are converted) and more accurate (no accent letters are left in
  1036.    words, for example "HTTX è bello" becomes "HTTX e` bello" while
  1037.    "Belphégor" will become "Belphegor".
  1038.   +As popular demand, default 7BIT option is now OFF.
  1039.   +Improved support for multiline comments and badly written HTML.
  1040.   +Added support for TAGS or ALT-Text that contains LF or "<" and ">".
  1041.   -Fixed many little aesthetical bugs in conversion (double spaces in some
  1042.    cases, bad chars exiting from <PRE> and <SCRIPT> and other).
  1043.   -Fixed an error that could cause a lock on file to convert.
  1044.   -Fixed an error in FILENOTE option.
  1045.  
  1046. V1.0  (July 1996)
  1047.    First public release.
  1048.  
  1049.  
  1050.  
  1051. 12. Future versions
  1052. -------------------
  1053.  
  1054. HTTX is a program in continuous growth, because I use it daily, I notice
  1055. lacks or possible improvements. This version will be the basis for a new even
  1056. better version that will be out... soon.
  1057.  
  1058.  
  1059.  
  1060. -----------------------------------------------------------------------------
  1061.  
  1062.                               *** CHILDWARE ***
  1063.  
  1064. This  software  is  "CHILDWARE". The author explicitly asks whoever uses this
  1065. program to make a donation to a beneficial corporate body which works helping
  1066. children in some way.
  1067.  
  1068. If  you  don't know of any, ask at your local post office and inform yourself
  1069. on how to make a donation to UNICEF.
  1070.  
  1071. The amount of the offer is up to you, but please do it!
  1072.  
  1073. -----------------------------------------------------------------------------
  1074.