Newer
Older
yatex / docs / yahtmle.tex
HIROSE Yuuji on 11 May 2012 16 KB Add `@directory' entries to info sources.
\def\lang{eng} % -*- texinfo -*- for Texinfo V.3.1 
\input texinfo
@setfilename yahtmle
@settitle Yet Another html-mode for Emacs
@direntry
* yahtml-e: (yahtmle).  Yet Another html-mode for Emacs (English).
@end direntry

@iftex
@c @syncodeindex fn cp
@c Last modified Fri May 11 15:42:22 2012 on firestorm
@syncodeindex vr cp
@end iftex

@titlepage
@sp 10
@center
@subtitle Yet Another html-mode for emacs
@title // yahtml //
%@subtitle // yahtml //
@author @copyright{} 1994-2012 by    HIROSE, Yuuji [yuuji@@yatex.org]
@end titlepage

@node Top, Intro, (dir), (dir)
@comment  node-name,  next,  previous,  up

@menu
* Intro::                       Introduction
* Installation::                Installing yahtml
* Command Invocation::          Using External Commands
* Completion::                  Input with Completion
* Jump::                        Moving the Cursor
* Changing and Deleting::       Changing and Deleting
* CSS Support::                 Style Sheet Support
* Customizations::              List of Customize Variables
* Copying::                     Copyright
* Concept Index::               Index
@end menu

@node Intro, Installation, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction
@cindex Demacs
@cindex Mule
@cindex LaTeX
@cindex yahtml

yahtml is a package to support creating HTML documents on Emacsens.  Easy
input of elements (tags) by completion, syntax checking with programs like
weblint, and invoking the appropriate browser or image viewer depending on
the cursor position is its main features.

(This Info is still incomplete)

@node Installation, Command Invocation, Intro, Top
@comment  node-name,  next,  previous,  up
@chapter Installing yahtml
@menu
* Setting up yahtml::           
* Setting environments for weblint browsers and image viewers::  
* Setting environment variables for WWW pages::  
@end menu

@node Setting up yahtml, Setting environments for weblint browsers and image viewers, Installation, Installation
@comment  node-name,  next,  previous,  up
@section Setting up yahtml


Add the following to @file{~/.emacs}

@lisp
(setq auto-mode-alist
      (cons (cons "\\.html$" 'yahtml-mode) auto-mode-alist))
(autoload 'yahtml-mode "yahtml" "Yet Another HTML mode" t)
@end lisp

Next, add to load-path the directory with the yahtml files
(@file{yahtml.el}, @file{yatexlib.el}, @file{yatexprc.el}).  For example,
if you put them in @file{~/src/emacs/yahtml},

@lisp
(setq load-path (cons (expand-file-name "~/src/emacs/yahtml") load-path))
@end lisp

@noindent
is what you add.

By this, yahtml will be automatically loaded when editing files with .html
extensions.  "yahtml" will be displayed on the mode line if no errors
occurred.

@node Setting environments for weblint browsers and image viewers, Setting environment variables for WWW pages, Setting up yahtml, Installation
@comment  node-name,  next,  previous,  up
@section Setting environments for weblint, browsers, and image viewers

Check the variables for invoking external commands and modify as needed.
Defaults are in parenthesis.

@table @code
@item yahtml-www-browser
        @dots{} browser command name (netscape)
@item yahtml-image-viewer
        @dots{} image viewer command name (xv)
@item yahtml-lint-program
        @dots{} syntax check programs command name (jweblint)
@item yahtml-kanji-code
        @dots{} kanji code for HTML files
@end table

@node Setting environment variables for WWW pages,  , Setting environments for weblint browsers and image viewers, Installation
@comment  node-name,  next,  previous,  up
@section Setting environment variables for WWW pages

Variables regarding path names for files that will be your home page.
@table @code
@item yahtml-path-url-alist
        @dots{} list of matching path name on file system and URLs
@item yahtml-directory-index
        @dots{} index file displayed when none is given in URL.  Usually
        @file{index.html} on NCSA type httpd and @file{Welcome.html} on
        CERN types.
@end table

Examples for  @code{yahtml-path-url-alist}.  If @file{/home/yuuji/http/}
is @code{http://localhost/~yuuji} at home and @file{/usr/home/yuuji/www/}
is @code{http://www.keio.ac.jp/~yuuji/} at work, then

@lisp
(setq yahtml-path-url-alist
      '(("/home/yuuji/http" . "http://localhost/~yuuji")
        ("/usr/home/yuuji/www" . "http://www.keio.ac.jp/~yuuji")))
@end lisp

Any number of additions can be made to this list.

@node Command Invocation, Completion, Installation, Top
@comment  node-name,  next,  previous,  up
@chapter Invoking external commands

For easy use of commands that are handy when editing HTML files.
@table @kbd
@item [prefix] t j
        @dots{} Invoke HTML syntax checker (jweblint)
@item [prefix] t p
        @dots{} Display current page in browser
@item [prefix] t r
        @dots{} Reload current page if browser is already running
@end table

@node Completion, Jump, Command Invocation, Top
@comment  node-name,  next,  previous,  up
@chapter Completion Input

Completion input of HTML elements is done through the same key strokes as
YaTeX's begin-type completion, section-type completion, large-type
completion, maketitle-type completion, and accent completion.
Corresponding elements in this order is; elements that span multiple
lines, empty elements such as img, tags that start and end in a
single line, elements with no attributes or contents, and special or
symbol entities.

@table @kbd
@item [prefix] b (YaTeX begin-type completion)
@dots{}
@example
<ul>
</ul>
@end example

@noindent
Completion for elements that the start tag and the end tag span multiple
lines. Mostly block-level elements.

@item [prefix] s (YateX section-type completion)
@dots{}
@example
<img src="foo.gif" alt="photo">
@end example

@noindent
Completion for elements that do not have end tags and require only
attributes.  Possible completions are, <img>, <input>.

@item [prefix] l (YaTeX large-type completion)
@dots{}

@example
<big> 〜 </big>
@end example

@noindent
Similar to begin-type completion but used for elements that start and end
on a single line.


@item [prefix] m (YaTeX maketitle-type completion)
@dots{} Completion for elements without attributes or contents.  Possible
completion is <br>

@item [prefix] a (YaTeX accent completion)
@dots{} Used to enter special or symbol entities.  By default completion
for < (&lt;), > (&gt;), & (&amp;), " (&quot;), ' (&apos;), blank (&nbsp;)
is possible.
@end table

@node Jump, Changing and Deleting, Completion, Top
@comment  node-name,  next,  previous,  up
@chapter Cursor Movement
By using

@table @kbd
@item [prefix] g
        @dots{} move to corresponding object
@end table

@noindent
the cursor will go to the corresponding object according to the context.
Recognized contexts are

@itemize @bullet
@item @code{<TAG>} <--> @code{</TAG>}
@item @code{<img src="image.file">} -> invoke viewer
@item @code{<a href="link.to.somewhere">} -> move cursor to linked target
@item @code{<applet code="program">} -> open Java source
@c @item @code{\include(\input)} → 対応するファイル
@end itemize

@node Changing and Deleting, CSS Support, Jump, Top
@comment  node-name,  next,  previous,  up
@chapter Changing and Deleting

@menu
* Changing tags in pairs::      
* Changing entities::           
* URLencoding of strings within region::  
* td-enclosure/tr-enclosure::   
@end menu

@node Changing tags in pairs, Changing entities, Changing and Deleting, Changing and Deleting
@comment  node-name,  next,  previous,  up
@section Changing tags in pairs
By using

@table @kbd
@item [prefix] c
        @dots{} change tags in matching pairs
@end table

@noindent
the content can be changed according to the context of the HTML document
where the cursor is located.

@itemize @bullet
@item @code{<TAG>}〜@code{</TAG>}
@dots{} change @code{TAG} element name
@item attributes such as @code{<img src="image.file" alt="photo">}
@dots{} change attributes
@end itemize

@node Changing entities, URLencoding of strings within region, Changing tags in pairs, Changing and Deleting
@comment  node-name,  next,  previous,  up
@section Changing entities
Special characters such as < or > must be written as &lt; and &gt;.  Easy
conversion of these characters can be done when importing text from non
HTML files.


@table @kbd
@item [prefix] ;
        @dots{} convert char to special entity in marked region
@item [prefix] :
        @dots{} convert special entity to original char in marked region
        (reverse of [prefix] ;)
@end table


@node URLencoding of strings within region, td-enclosure/tr-enclosure, Changing entities, Changing and Deleting
@comment  node-name,  next,  previous,  up
@section URLencoding of strings within region

@table @kbd
@item [prefix] #
	@dots{} encode chars that needs to be URLencoded within region
@end table

@node  td-enclosure/tr-enclosure,  , URLencoding of strings within region, Changing and Deleting
@comment  node-name,  next,  previous,  up
@section td-enclosure/tr-enclosure
If you wan to convert series of field into <td>...</td> repetitions for
table element, td-enclosure or tr-enclosure is convenient.

@table @kbd
 @item [prefix] @}
	@dots{} Enclose each field in a region into <td>...</td>'s.
 @item [prefix] ]
	@dots{} Enclose each line in a region into <tr>...</tr>'s, with
        every line converted to <td>...</td> repetition.
@end table
They presume white space as field separator by default.
To change this, enter other delimiting character for a query.
You can convert CSV, for example, into table by specifying
comma(,) as a delimiter.

If you want to enclose fields with th, call with
universal-argument (@kbd{C-u}).  Enter `th' to enclose fields
with <th>...</th>.  The special answer `thd' means that
enclose the only first column with th, and the rest with td.

@node CSS Support, Customizations, Changing and Deleting, Top
@comment  node-name,  next,  previous,  up
@chapter CSS(Style Sheets) Support

@menu
* CSS-class completion::        
* Reread CSS definition::       
@end menu

@node CSS-class completion, Reread CSS definition, CSS Support, CSS Support
@comment  node-name,  next,  previous,  up
@section CSS class-name completion
You can input a class name in your CSS definition with completion.
If you have CSS defined as below;

@display
 h1.foo, h2.foo @{ background-color: 0xffffff; @}
 h1.bar, h2.bar @{ font-size: 120%; @}
@end display

when you input h1(or h2) tag with completing-read by [prefix] b or
[prefix] l, yahtml prompts you to input class name with completion from
the words which are effective to h1 or h2.  And if you defined
global class like this;

@display
 .caution @{ font-size: 120%; background-color: 0xc00000;@}
@end display

when you input any tags via completing-read, yahtml prompts you to input
class name.  If this is bothering, typing @kbd{C-j} instead of
@kbd{RET} (or @kbd{C-m}) cancels the next prompt to class name completion.

@node Reread CSS definition,  , CSS-class completion, CSS Support
@comment  node-name,  next,  previous,  up
@section Re-reading CSS definition
If you add some class to your CSS file and you want yahtml to load
new definitions, type @kbd{M-x yahtml-mode RET} to make yahtml do.

@node Customizations, Copying, CSS Support, Top
@comment  node-name,  next,  previous,  up
@chapter Customizations
@cindex Customize
@cindex Key Assign

Variables that modify yahtml's behavior.

@menu
* All customizable variables::  List of customizable variables
* Hook variables::              hook variables
@end menu

@node All customizable variables, Hook variables, Customizations, Customizations
@comment  node-name,  next,  previous,  up
@section List of customizable variables.  Defaults in parenthesis

@defvar yahtml-prefix
Prefix key for yahtml-mode.  (@kbd{\C-c})
@end defvar

@defvar yahtml-image-viewer
Command to view image files refered by img. (xv)
@end defvar

@defvar yahtml-www-browser
Browser to view external pages with @kbd{[prefix]g}. (netscape)
@end defvar

@defvar yahtml-kanji-code
Default kanji code. 1=sjis, 2=jis, 3=euc, 4=utf-8 (2)
If
@quotation
 AddType "text/html; charset=xxx" .html
@end quotation
is written in .htaccess, this will override yahtml-kanji-code.
@end defvar

@defvar yahtml-fill-column
Columns to auto-fill (72)
@end defvar

@defvar yahtml-fill-prefix
fill-prefix specific to yahtml-mode. (@code{nil})
@end defvar

@defvar yahtml-path-url-alist
Matching list of URL and full path name on OS's file system.
@end defvar

@defvar yahtml-directory-index
Default index filed opened when accessing a server without a filename,
usually index.html. (@code{"index.html"})
@end defvar

@defvar yahtml-lint-program
HTML syntax check program. (@code{"jweblint"})
@end defvar

@defvar yahtml-hate-too-deep-indentation
setq to t when indentations for nested enumerate elements are too deep.
(@code{nil})
@end defvar

@defvar yahtml-always-/p
setq to t if you always want @code{</p>} after @code{</p>}. @code{nil}
@end defvar

@defvar yahtml-p-prefered-env-regexp
Elements that @code{<p>} will be automatically inserted.
(@code{"^\\(body\\|dl\\|blockquote\\)"})
@end defvar

@defvar yahtml-template-file
File to automatically insert when editing a new HTML file.
@file{"~/http/template.html"}
@end defvar

@defvar yahtml-prefer-upcases
Use uppercase for tags. @code{nil}
@end defvar

@defvar yahtml-prefer-upcase-attributes
Use uppercase for attributes. @code{nil}
@end defvar

@defvar yahtml-server-type
setq to 'apache if using a Apache server, and will refer ./.htaccess.
@code{'apache}
@end defvar

@defvar yahtml-apache-access-file
When @code{yahtml-server-type} is @code{'apache}, define name of access
restriction file. @file{".htaccess"}
@end defvar

@defvar yahtml-shell-command-option
Options needed to invoke shell commands.
@end defvar

@defvar yahtml-translate-hyphens-when-comment-region
Whether to change hyphens to @code{&#45;} when commenting out region.
(@code{t})
@end defvar

@defvar yahtml-entity-reference-chars-alist
alist of characters that needs to be written by Entity Reference.  Enter
as @code{'(?char . "EntityReference")}.  By default, @code{<}, @code{>},
@code{&}, @code{'}, is set.  Add as needed.  Do not include @code{&} at
beginning and @code{;} at end of cdr portion of @code{"EntityReference"}.
@end defvar

@defvar yahtml-faithful-to-htmllint
When using htmllint to check syntax, it will complain about excess spaces.
setq to @code{t} to avoid this.
@end defvar

@defvar yahtml-use-css
Use style-sheet support or not (@code{t})
@end defvar

@defvar yahtml-image-inspection-bytes
Number of bytes to inspect the image for geometry information (@code{10000})
@end defvar

@defvar yahtml:img-default-alt-format
format of img entity's ALT attributes.
%x: width, %y: height, %s: size in bytes, %c: first comment string,
%f: filename (@code{"%xx%y(%sbytes)"})
@end defvar

@defvar yahtml-escape-chars
When, completing href-s, Escape reserved characters to URL-encoding or not.
Nil for never, t for everytime, and 'ask for inquiring
at each reserved chars. (@code{'ask})
@end defvar

@defvar yahtml-use-font-lock
Use font-lock to fontify buffer or not
(@code{(featurep 'font-lock)})
@end defvar

@defvar yahtml-use-hilit19
Use hilit19 to highlight buffer or not
(@code{(featurep 'hilit19)})
@end defvar

@defvar yahtml-indentation-boundary
Boundary regexp for indentation calculation.
(@code{"^\\s *<h[1-3]>"})
@end defvar

@node Hook variables,  , All customizable variables, Customizations
@comment  node-name,  next,  previous,  up
@section hook variables


@node Copying, Concept Index, Customizations, Top
@comment  node-name,  next,  previous,  up
@chapter Copying

This program is distributed as freesoftware.  The author will take no
responsibility to any damages due to the usage of this software
whatsoever.  There are no restrictions to its redistribution, just use
common sense.  Mail me your thoughts on this program and I will be more
than willing to help.

Complaints, requests, bug reports and comments are welcome.  Make contacts
to yuuji@@yatex.org (as of December 2000)

If you like this program and use it on a regular basis, please join the
mailing list "fj Wild Bird Society".  Procedures can be found in the "etc"
section of @file{docs/htmlqa.eng} in this package.


@flushright
HIROSE, Yuuji
@end flushright


@node    Concept Index,  , Copying, Top
@comment node-name, next, previous, up
@unnumbered Index
@printindex cp


@contents

@bye

@c Local Variables:
@c fill-column: 74
@c fill-prefix: nil
@c End:

Tag table:

End tag table