1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/yahtmle.tex	Sun Apr 09 03:37:47 2000 +0000
     1.3 @@ -0,0 +1,485 @@
     1.4 +\def\lang{eng} % -*- texinfo -*- for Texinfo V.3.1 
     1.5 +\input texinfo
     1.6 +@setfilename yahtmle
     1.7 +@settitle Yet Another html-mode for Emacs
     1.8 +
     1.9 +@iftex
    1.10 +@c @syncodeindex fn cp
    1.11 +@c Do people really read this INFO?
    1.12 +@c Still not finished
    1.13 +@c Last modified Mon Nov 29 16:01:00 1999 on buell
    1.14 +@syncodeindex vr cp
    1.15 +@end iftex
    1.16 +
    1.17 +@titlepage
    1.18 +@sp 10
    1.19 +@center
    1.20 +@subtitle Yet Another html-mode for emacs
    1.21 +@title // yahtml //
    1.22 +%@subtitle // yahtml //
    1.23 +@author @copyright{} 1994-1997 by    HIROSE, Yuuji [yuuji@@yatex.org]
    1.24 +@end titlepage
    1.25 +
    1.26 +@node Top, Intro, (dir), (dir)
    1.27 +@comment  node-name,  next,  previous,  up
    1.28 +
    1.29 +@menu
    1.30 +* Intro::                       Introduction
    1.31 +* Installation::                Installing yahtml
    1.32 +* Command Invocation::          Using External Commands
    1.33 +* Completion::                  Input with Completion
    1.34 +* Jump::                        Moving the Cursor
    1.35 +* Changing and Deleting::       Changing and Deleting
    1.36 +* CSS Support::                 Style Sheet Support
    1.37 +* Customizations::              List of Customize Variables
    1.38 +* Copying::                     Copyright
    1.39 +* Concept Index::               Index
    1.40 +@end menu
    1.41 +
    1.42 +@node Intro, Installation, Top, Top
    1.43 +@comment  node-name,  next,  previous,  up
    1.44 +@chapter Introduction
    1.45 +@cindex Demacs
    1.46 +@cindex Mule
    1.47 +@cindex LaTeX
    1.48 +@cindex yahtml
    1.49 +
    1.50 +yahtml is a package to support creating HTML documents on Emacsens.  Easy
    1.51 +input of elements (tags) by completion, syntax checking with programs like
    1.52 +weblint, and invoking the appropriate browser or image viewer depending on
    1.53 +the cursor position is its main features.
    1.54 +
    1.55 +(This Info is still incomplete)
    1.56 +
    1.57 +@node Installation, Command Invocation, Intro, Top
    1.58 +@comment  node-name,  next,  previous,  up
    1.59 +@chapter Installing yahtml
    1.60 +@menu
    1.61 +* Setting up yahtml::           
    1.62 +* Setting environments for weblint browsers and image viewers::  
    1.63 +* Setting environment variables for WWW pages::  
    1.64 +@end menu
    1.65 +
    1.66 +@node Setting up yahtml, Setting environments for weblint browsers and image viewers, Installation, Installation
    1.67 +@comment  node-name,  next,  previous,  up
    1.68 +@section Setting up yahtml
    1.69 +
    1.70 +
    1.71 +Add the following to @file{~/.emacs}
    1.72 +
    1.73 +@lisp
    1.74 +(setq auto-mode-alist
    1.75 +      (cons (cons "\\.html$" 'yahtml-mode) auto-mode-alist))
    1.76 +(autoload 'yahtml-mode "yahtml" "Yet Another HTML mode" t)
    1.77 +@end lisp
    1.78 +
    1.79 +Next, add to load-path the directory with the yahtml files
    1.80 +(@file{yahtml.el}, @file{yatexlib.el}, @file{yatexprc.el}).  For example,
    1.81 +if you put them in @file{~/src/emacs/yahtml},
    1.82 +
    1.83 +@lisp
    1.84 +(setq load-path (cons (expand-file-name "~/src/emacs/yahtml") load-path))
    1.85 +@end lisp
    1.86 +
    1.87 +@noindent 
    1.88 +is what you add.
    1.89 +
    1.90 +By this, yahtml will be automatically loaded when editing files with .html
    1.91 +extensions.  "yahtml" will be displayed on the mode line if no errors
    1.92 +occurred. 
    1.93 +
    1.94 +@node Setting environments for weblint browsers and image viewers, Setting environment variables for WWW pages, Setting up yahtml, Installation
    1.95 +@comment  node-name,  next,  previous,  up
    1.96 +@section Setting environments for weblint, browsers, and image viewers
    1.97 +
    1.98 +Check the variables for invoking external commands and modify as needed.
    1.99 +Defaults are in parenthesis.
   1.100 +
   1.101 +@table @code
   1.102 +@item yahtml-www-browser
   1.103 +        @dots{} browser command name (netscape)
   1.104 +@item yahtml-image-viewer
   1.105 +        @dots{} image viewer command name (xv)
   1.106 +@item yahtml-lint-program
   1.107 +        @dots{} syntax check programs command name (jweblint)
   1.108 +@item yahtml-kanji-code
   1.109 +        @dots{} kanji code for HTML files
   1.110 +@end table
   1.111 +
   1.112 +@node Setting environment variables for WWW pages,  , Setting environments for weblint browsers and image viewers, Installation
   1.113 +@comment  node-name,  next,  previous,  up
   1.114 +@section Setting environment variables for WWW pages
   1.115 +
   1.116 +Variables regarding path names for files that will be your home page.
   1.117 +@table @code
   1.118 +@item yahtml-path-url-alist
   1.119 +        @dots{} list of matching path name on file system and URLs
   1.120 +@item yahtml-directory-index
   1.121 +        @dots{} index file displayed when none is given in URL.  Usually
   1.122 +        @file{index.html} on NCSA type httpd and @file{Welcome.html} on
   1.123 +        CERN types. 
   1.124 +@end table
   1.125 +
   1.126 +Examples for  @code{yahtml-path-url-alist}.  If @file{/home/yuuji/http/}
   1.127 +is @code{http://localhost/~yuuji} at home and @file{/usr/home/yuuji/www/}
   1.128 +is @code{http://www.keio.ac.jp/~yuuji/} at work, then
   1.129 +
   1.130 +@lisp
   1.131 +(setq yahtml-path-url-alist
   1.132 +      '(("/home/yuuji/http" . "http://localhost/~yuuji")
   1.133 +        ("/usr/home/yuuji/www" . "http://www.keio.ac.jp/~yuuji")))
   1.134 +@end lisp
   1.135 +
   1.136 +Any number of additions can be made to this list.
   1.137 +
   1.138 +@node Command Invocation, Completion, Installation, Top
   1.139 +@comment  node-name,  next,  previous,  up
   1.140 +@chapter Invoking external commands
   1.141 +
   1.142 +For easy use of commands that are handy when editing HTML files.
   1.143 +@table @kbd
   1.144 +@item [prefix] t j
   1.145 +        @dots{} Invoke HTML syntax checker (jweblint)
   1.146 +@item [prefix] t p
   1.147 +        @dots{} Display current page in browser
   1.148 +@item [prefix] t r
   1.149 +        @dots{} Reload current page if browser is already running
   1.150 +@end table
   1.151 +
   1.152 +@node Completion, Jump, Command Invocation, Top
   1.153 +@comment  node-name,  next,  previous,  up
   1.154 +@chapter Completion Input
   1.155 +
   1.156 +Completion input of HTML elements is done through the same key strokes as
   1.157 +YaTeX's begin-type completion, section-type completion, large-type
   1.158 +completion, maketitle-type completion, and accent completion.
   1.159 +Corresponding elements in this order is; elements that span multiple
   1.160 +lines, empty elements such as img, tags that start and end in a
   1.161 +single line, elements with no attributes or contents, and special or
   1.162 +symbol entities.
   1.163 +
   1.164 +@table @kbd
   1.165 +@item [prefix] b (YaTeX begin-type completion)
   1.166 +@dots{}
   1.167 +@example
   1.168 +<ul>
   1.169 +</ul>
   1.170 +@end example
   1.171 +
   1.172 +@noindent
   1.173 +Completion for elements that the start tag and the end tag span multiple
   1.174 +lines. Mostly block-level elements.
   1.175 +
   1.176 +@item [prefix] s (YateX section-type completion)
   1.177 +@dots{}
   1.178 +@example
   1.179 +<img src="foo.gif" alt="photo">
   1.180 +@end example
   1.181 +
   1.182 +@noindent
   1.183 +Completion for elements that do not have end tags and require only
   1.184 +attributes.  Possible completions are, <img>, <input>.
   1.185 +
   1.186 +@item [prefix] l (YaTeX large-type completion)
   1.187 +@dots{} 
   1.188 +
   1.189 +@example
   1.190 +<big> 〜 </big>
   1.191 +@end example
   1.192 +
   1.193 +@noindent
   1.194 +Similar to begin-type completion but used for elements that start and end
   1.195 +on a single line.
   1.196 +
   1.197 +
   1.198 +@item [prefix] m (YaTeX maketitle-type completion)
   1.199 +@dots{} Completion for elements without attributes or contents.  Possible
   1.200 +completion is <br>
   1.201 +
   1.202 +@item [prefix] a (YaTeX accent completion)
   1.203 +@dots{} Used to enter special or symbol entities.  By default completion
   1.204 +for < (&lt;), > (&gt;), & (&amp;), " (&quot;), ' (&apos;), blank (&nbsp;)
   1.205 +is possible.
   1.206 +@end table
   1.207 +
   1.208 +@node Jump, Changing and Deleting, Completion, Top
   1.209 +@comment  node-name,  next,  previous,  up
   1.210 +@chapter Cursor Movement
   1.211 +By using 
   1.212 +
   1.213 +@table @kbd
   1.214 +@item [prefix] g
   1.215 +        @dots{} move to corresponding object
   1.216 +@end table
   1.217 +
   1.218 +@noindent 
   1.219 +the cursor will go to the corresponding object according to the context.
   1.220 +Recognized contexts are
   1.221 +
   1.222 +@itemize @bullet
   1.223 +@item @code{<TAG>} <--> @code{</TAG>}
   1.224 +@item @code{<img src="image.file">} -> invoke viewer
   1.225 +@item @code{<a href="link.to.somewhere">} -> move cursor to linked target
   1.226 +@item @code{<applet code="program">} -> open Java source
   1.227 +@c @item @code{\include(\input)} → 対応するファイル
   1.228 +@end itemize
   1.229 +
   1.230 +@node Changing and Deleting, CSS Support, Jump, Top
   1.231 +@comment  node-name,  next,  previous,  up
   1.232 +@chapter Changing and Deleting
   1.233 +
   1.234 +@menu
   1.235 +* Changing tags in pairs::      
   1.236 +* Changing entities::           
   1.237 +* URLencoding of strings within region::  
   1.238 +@end menu
   1.239 +
   1.240 +@node Changing tags in pairs, Changing entities, Changing and Deleting, Changing and Deleting
   1.241 +@comment  node-name,  next,  previous,  up
   1.242 +@section Changing tags in pairs
   1.243 +By using
   1.244 +
   1.245 +@table @kbd
   1.246 +@item [prefix] c
   1.247 +        @dots{} change tags in matching pairs
   1.248 +@end table
   1.249 +
   1.250 +@noindent 
   1.251 +the content can be changed according to the context of the HTML document
   1.252 +where the cursor is located.
   1.253 +
   1.254 +@itemize @bullet
   1.255 +@item @code{<TAG>}〜@code{</TAG>}
   1.256 +@dots{} change @code{TAG} element name
   1.257 +@item attributes such as @code{<img src="image.file" alt="photo">}
   1.258 +@dots{} change attributes
   1.259 +@end itemize
   1.260 +
   1.261 +@node Changing entities, URLencoding of strings within region, Changing tags in pairs, Changing and Deleting
   1.262 +@comment  node-name,  next,  previous,  up
   1.263 +@section Changing entities
   1.264 +Special characters such as < or > must be written as &lt; and &gt;.  Easy
   1.265 +conversion of these characters can be done when importing text from non
   1.266 +HTML files.
   1.267 +
   1.268 +
   1.269 +@table @kbd
   1.270 +@item [prefix] ;
   1.271 +        @dots{} convert char to special entity in marked region
   1.272 +@item [prefix] :
   1.273 +        @dots{} convert special entity to original char in marked region
   1.274 +        (reverse of [prefix] ;)
   1.275 +@end table
   1.276 +
   1.277 +
   1.278 +@node URLencoding of strings within region,  , Changing entities, Changing and Deleting
   1.279 +@comment  node-name,  next,  previous,  up
   1.280 +@section URLencoding of strings within region
   1.281 +
   1.282 +@table @kbd
   1.283 +@item [prefix] #
   1.284 +	@dots{} encode chars that needs to be URLencoded within region
   1.285 +@end table
   1.286 +
   1.287 +@node CSS Support, Customizations, Changing and Deleting, Top
   1.288 +@comment  node-name,  next,  previous,  up
   1.289 +@chapter CSS(Style Sheets) Support
   1.290 +
   1.291 +@menu
   1.292 +* CSS-class completion::        
   1.293 +* Reread CSS definition::       
   1.294 +@end menu
   1.295 +
   1.296 +@node CSS-class completion, Reread CSS definition, CSS Support, CSS Support
   1.297 +@comment  node-name,  next,  previous,  up
   1.298 +@section CSS class-name completion
   1.299 +You can input a class name in your CSS definition with completion.
   1.300 +If you have CSS defined as below;
   1.301 +
   1.302 +@display
   1.303 + h1.foo, h2.foo @{ background-color: 0xffffff; @}
   1.304 + h1.bar, h2.bar @{ font-size: 120%; @}
   1.305 +@end display
   1.306 +
   1.307 +when you input h1(or h2) tag with completing-read by [prefix] b or
   1.308 +[prefix] l, yahtml prompts you to input class name with completion from
   1.309 +the words which are effective to h1 or h2.  And if you defined 
   1.310 +global class like this;
   1.311 +
   1.312 +@display
   1.313 + .caution @{ font-size: 120%; background-color: 0xc00000;@}
   1.314 +@end display
   1.315 +
   1.316 +when you input any tags via completing-read, yahtml prompts you to input
   1.317 +class name.  If this is bothering, typing @kbd{C-j} instead of
   1.318 +@kbd{RET} (or @kbd{C-m}) cancels the next prompt to class name completion.
   1.319 +
   1.320 +@node Reread CSS definition,  , CSS-class completion, CSS Support
   1.321 +@comment  node-name,  next,  previous,  up
   1.322 +@section Re-reading CSS definition
   1.323 +If you add some class to your CSS file and you want yahtml to load
   1.324 +new definitions, type @kbd{M-x yahtml-mode RET} to make yahtml do.
   1.325 +
   1.326 +@node Customizations, Copying, CSS Support, Top
   1.327 +@comment  node-name,  next,  previous,  up
   1.328 +@chapter Customizations
   1.329 +@cindex Customize
   1.330 +@cindex Key Assign
   1.331 +
   1.332 +Variables that modify yahtml's behavior.
   1.333 +
   1.334 +@menu
   1.335 +* All customizable variables::  List of customizable variables
   1.336 +* Hook variables::              hook variables
   1.337 +@end menu
   1.338 +
   1.339 +@node All customizable variables, Hook variables, Customizations, Customizations
   1.340 +@comment  node-name,  next,  previous,  up
   1.341 +@section List of customizable variables.  Defaults in parenthesis
   1.342 +
   1.343 +@defvar yahtml-prefix
   1.344 +Prefix key for yahtml-mode.  (@kbd{\C-c})
   1.345 +@end defvar
   1.346 +
   1.347 +@defvar yahtml-image-viewer
   1.348 +Command to view image files refered by img. (xv)
   1.349 +@end defvar
   1.350 +
   1.351 +@defvar yahtml-www-browser
   1.352 +Browser to view external pages with @kbd{[prefix]g}. (netscape)
   1.353 +@end defvar
   1.354 +
   1.355 +@defvar yahtml-kanji-code
   1.356 +Default kanji code. 1=sjis, 2=jis, 3=euc (2)
   1.357 +If
   1.358 +@quotation
   1.359 + AddType "text/html; charset=xxx" .html
   1.360 +@end quotation
   1.361 +is written in .htaccess, this will override yahtml-kanji-code.
   1.362 +@end defvar
   1.363 +
   1.364 +@defvar yahtml-fill-column
   1.365 +Columns to auto-fill (72)
   1.366 +@end defvar
   1.367 +
   1.368 +@defvar yahtml-fill-prefix
   1.369 +fill-prefix specific to yahtml-mode. (@code{nil})
   1.370 +@end defvar
   1.371 +
   1.372 +@defvar yahtml-path-url-alist
   1.373 +Matching list of URL and full path name on OS's file system.
   1.374 +@end defvar
   1.375 +
   1.376 +@defvar yahtml-directory-index
   1.377 +Default index filed opened when accessing a server without a filename,
   1.378 +usually index.html. (@code{"index.html"})
   1.379 +@end defvar
   1.380 +
   1.381 +@defvar yahtml-lint-program
   1.382 +HTML syntax check program. (@code{"jweblint"})
   1.383 +@end defvar
   1.384 +
   1.385 +@defvar yahtml-hate-too-deep-indentation
   1.386 +setq to t when indentations for nested enumerate elements are too deep.
   1.387 +(@code{nil})
   1.388 +@end defvar
   1.389 +
   1.390 +@defvar yahtml-always-/p
   1.391 +setq to t if you always want @code{</p>} after @code{</p>}. @code{nil}
   1.392 +@end defvar
   1.393 +
   1.394 +@defvar yahtml-p-prefered-env-regexp
   1.395 +Elements that @code{<p>} will be automatically inserted. @code{^\(body\|dl\)}
   1.396 +@end defvar
   1.397 +
   1.398 +@defvar yahtml-template-file
   1.399 +File to automatically insert when editing a new HTML file.
   1.400 +@file{"~/http/template.html"}
   1.401 +@end defvar
   1.402 +
   1.403 +@defvar yahtml-prefer-upcases
   1.404 +Use uppercase for tags. @code{nil}
   1.405 +@end defvar
   1.406 +
   1.407 +@defvar yahtml-prefer-upcase-attributes
   1.408 +Use uppercase for attributes. @code{nil}
   1.409 +@end defvar
   1.410 +
   1.411 +@defvar yahtml-server-type
   1.412 +setq to 'apache if using a Apache server, and will refer ./.htaccess.
   1.413 +@code{'apache}
   1.414 +@end defvar
   1.415 +
   1.416 +@defvar yahtml-apache-access-file
   1.417 +When @code{yahtml-server-type} is @code{'apache}, define name of access
   1.418 +restriction file. @file{".htaccess"}
   1.419 +@end defvar
   1.420 +
   1.421 +@defvar yahtml-shell-command-option
   1.422 +Options needed to invoke shell commands.
   1.423 +@end defvar
   1.424 +
   1.425 +@defvar yahtml-translate-hyphens-when-comment-region
   1.426 +Whether to change hyphens to @code{&#45;} when commenting out region.
   1.427 +(@code{t})
   1.428 +@end defvar
   1.429 +
   1.430 +@defvar yahtml-entity-reference-chars-alist
   1.431 +alist of characters that needs to be written by Entity Reference.  Enter
   1.432 +as @code{'(?char . "EntityReference")}.  By default, @code{<}, @code{>},
   1.433 +@code{&}, @code{'}, is set.  Add as needed.  Do not include @code{&} at
   1.434 +beginning and @code{;} at end of cdr portion of @code{"EntityReference"}.
   1.435 +@end defvar
   1.436 +
   1.437 +@defvar yahtml-faithful-to-htmllint
   1.438 +When using htmllint to check syntax, it will complain about excess spaces.
   1.439 +setq to @code{t} to avoid this.
   1.440 +@end defvar
   1.441 +
   1.442 +
   1.443 +@node Hook variables,  , All customizable variables, Customizations
   1.444 +@comment  node-name,  next,  previous,  up
   1.445 +@section hook variables
   1.446 +
   1.447 +
   1.448 +@node Copying, Concept Index, Customizations, Top
   1.449 +@comment  node-name,  next,  previous,  up
   1.450 +@chapter Copying
   1.451 +
   1.452 +This program is distributed as freesoftware.  The author will take no
   1.453 +responsibility to any damages due to the usage of this software
   1.454 +whatsoever.  There are no restrictions to its redistribution, just use
   1.455 +common sense.  Mail me your thoughts on this program and I will be more
   1.456 +than willing to help.
   1.457 +
   1.458 +Complaints, requests, bug reports and comments are welcome.  Make contacts
   1.459 +to yuuji@@yatex.org　(as of July 1999)
   1.460 +
   1.461 +If you like this program and use it on a regular basis, please join the
   1.462 +mailing list "fj Wild Bird Society".  Procedures can be found in the "etc"
   1.463 +section of @file{docs/yahtmlqa} in this package.
   1.464 +
   1.465 +
   1.466 +@flushright
   1.467 +HIROSE, Yuuji
   1.468 +@end flushright
   1.469 +
   1.470 +
   1.471 +@node    Concept Index,  , Copying, Top
   1.472 +@comment node-name, next, previous, up
   1.473 +@unnumbered Index
   1.474 +@printindex cp
   1.475 +
   1.476 +
   1.477 +@contents
   1.478 +
   1.479 +@bye
   1.480 +
   1.481 +@c Local Variables:
   1.482 +@c fill-column: 74
   1.483 +@c fill-prefix: nil
   1.484 +@c End:
   1.485 +
   1.486 +Tag table:
   1.487 +
   1.488 +End tag table