Changeset 31875 in project


Ignore:
Timestamp:
11/20/14 16:17:34 (5 years ago)
Author:
Moritz Heidkamp
Message:

hyde: Update documentation for version 0.21.0

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/hyde

    r29397 r31875  
    1515=== Requirements
    1616
    17 
    18 Requires the [[environments]], [[sxml-transforms]], [[matchable]],
    19 [[scss]], [[filepath]], [[spiffy]], [[doctype]], [[colorize]], [[multidoc]],
    20 [[defstruct]], [[atom]] and [[rfc3339]] extensions.
     17Requires the [[sxml-transforms]], [[matchable]], [[scss]],
     18[[filepath]], [[spiffy]], [[uri-common]], [[doctype]], [[colorize]],
     19[[multidoc]], [[defstruct]], [[atom]], [[svnwiki-sxml]] and
     20[[rfc3339]] extensions.
    2121
    2222Although there is a native
     
    241241<parameter>(page-eval-env [env])</parameter>
    242242
    243 The environment for evaluating SXML and SCSS files. Default:
    244 {{(environment-copy (interaction-environment) #t)}}
    245 
    246 
    247 <parameter>(translators [translators-alist])</parameter>
    248 
    249 An alist of source language translators indexed by file extensions. Default:
    250 
    251     `(("sxml" . ,hyde#translate/sxml)
    252       ("scss" . ,hyde#translate/scss)
    253       ("md"   . ,hyde#translate/markdown)
    254       ("wiki" . ,hyde#translate/svnwiki)
    255       ("sw"   . ,hyde#translate/svnwiki))
    256 
    257 Additionally, {{("atom" . ,hyde-atom#translate/atom)}} can be made
    258 available by loading the {{hyde-atom}} extension from the site's
    259 {{hyde.scm}}.
     243The environment for evaluating SXML and SCSS pages. It needs to be an
     244environment created via the {{hyde-page-eval-env}} module which is a
     245(mostly) drop-in replacement for the deprecated
     246[[/egg/environments|environments egg]]. Note that the top-level
     247environment is always used as a fallback for lookup.
    260248
    261249
     
    284272
    285273This parameter has been added in version 0.16.
     274
     275
     276<parameter>(ignore-page? [predicate])</parameter>
     277
     278
     279=== Page accessors
     280
     281<parameter>pages</parameter>
     282
     283An alist of all available pages indexed by their source file names
     284relative to {{(source-dir)}}. The values are {{page}} records. Note
     285that it is only bound during site compilation, i.e. not yet when
     286{{hyde.scm}} is loaded.
     287
     288This used to be a constant up until version 0.13 and was only
     289available in the {{page-eval-env}} up until 0.20.0.
     290
     291<procedure>(page-by-path path)</procedure>
     292
     293Looks up a page by its target {{path}} (i.e. {{page-path}}), which can
     294be given as a string or a list of strings representing the path
     295components.
     296
     297<procedure>(current-page)</procedure>
     298
     299Returns the current page's record. Only bound during compilation.
     300
     301
     302<procedure>(page-path page)</procedure>
     303
     304Returns the given {{page}}'s absolute URI path.
     305
     306
     307<procedure>(page-source-path page)</procedure>
     308
     309Returns the given {{page}}'s source path relative to {{(source-dir)}}.
     310
     311
     312<procedure>(page-vars page)</procedure>
     313
     314Returns the given {{page}}'s page-vars as an alist.
     315
     316
     317<procedure>(page-type page)</procedure>
     318
     319Returns the given {{page}}'s type which is one of the following symbols:
     320
     321; dynamic : a page which is handled by one of Hyde's page translators
     322; static : a page which is just copied to {{(output-dir)}}
     323; directory : a directory
     324
     325
     326<procedure>(read-page page #!rest layouts)</procedure>
     327
     328Returns the given {{page}}'s contents, possibly wrapped in the given
     329{{layouts}}. {{page}} may be either a {{page}} record or a path
     330relative to {{(source-dir)}}. This procedure is useful to create
     331aggregate pages. Note that it will translate the contents of dynamic
     332{{page}}s even if they have not been compiled, yet. In this case, they
     333will neither be wrapped in page-specific nor the default layouts, only
     334the ones given in {{layouts}}.
     335
     336
     337=== Translators
     338
     339A ''translator'' is a zero-argument procedure which is expected to
     340read the contents of a Hyde page from {{(current-input-port)}} and
     341write its translation to {{(current-output-port)}}. For example, the
     342SXML translator shipped with Hyde reads s-expressions from
     343{{(current-input-port)}}, evaluates them in {{(page-eval-env)}},
     344applies {{sxml-conversion-rules}} and finally writes the result
     345renderd as HTML to {{(current-output-port)}}. Note The page-vars
     346preamble has already been read and interpreted at the point a
     347translator is called. The page being translated is available via
     348{{(current-page)}}.
     349
     350<procedure>(translate-sxml)</procedure>
     351<procedure>(translate-scss)</procedure>
     352<procedure>(translate-markdown)</procedure>
     353<procedure>(translate-svnwiki)</procedure>
     354
     355Translators for SXML, SCSS, Markdown and svnwiki formatted pages. See
     356{{translators}} parameter for which files extensions they are mapped
     357to.
     358
     359
     360<parameter>(translators [translators-alist])</parameter>
     361
     362An alist of source language translators indexed by file extensions. Default:
     363
     364<enscript language="scheme">
     365    `(("sxml" . ,translate-sxml)
     366      ("scss" . ,translate-scss)
     367      ("md"   . ,translate-markdown)
     368      ("wiki" . ,translate-svnwiki)
     369      ("sw"   . ,translate-svnwiki))
     370</enscript>
     371
     372Additionally, {{("atom" . ,translate-atom)}} can be made available by
     373loading the {{hyde-atom}} extension from your site's {{hyde.scm}}.
     374
     375To use [[/egg/lowdown|Lowdown]] for
     376[[http://daringfireball.net/projects/markdown/|Markdown]] pages you
     377need to define a custom page translator in your site's {{hyde.scm}}
     378like this:
     379
     380<enscript language="scheme">
     381(use lowdown)
     382(translators (cons (list "md" markdown->html) (translators)))
     383</enscript>
     384
     385
     386<procedure>(make-external-translator program-name [args])</procedure>
     387
     388Creates a procedure that reads from {{(current-input-port)}} and
     389writes to the standard input of the external program {{program-name}}
     390(either a string or a thunk returning a string). Optionally a thunk
     391can be passed for {{args}} which needs to return a list of arguments
     392for the program. The program's standard output is read back and
     393written to {{(current-output-port)}}. It can be used to create page
     394translators for external programs, e.g. the markdown translator
     395included in Hyde is defined like this:
     396
     397<enscript language="scheme">
     398(define translate-markdown (make-external-translator markdown-program))
     399(translators (cons (list "md" translate-markdown) (translators)))
     400</enscript>
    286401
    287402
     
    302417respect environments.
    303418
    304 
    305 <syntax>(make-external-translator name)</syntax>
    306 
    307 Creates a procedure that reads from {{(current-input-port)}} and
    308 writes to the standard input of the program {{name}}
    309 linewise. Afterwards, its standard output is read back and written to
    310 {{(current-output-port)}}, also linewise. It can be used to create
    311 page translators for external programs, e.g. the markdown translator
    312 included in Hyde is defined like this:
    313 
    314 <enscript language="scheme">
    315 (define translate/markdown (make-external-translator (markdown-program)))
    316 (translators (cons (list "md" translate/markdown) (translators)))
    317 </enscript>
    318 
    319 
    320419<procedure>(pathify string)</procedure>
    321420
     
    336435
    337436Exported since version 0.15.
     437
     438
     439<procedure>(serve-page page path continue)</procedure>
     440
     441Default handler for the {{hyde serve}} command which translates
     442dynamic pages when requested by their target path and tries to serve
     443index files for directories as defined via [[/egg/spiffy|Spiffy]]'s
     444{{index-files}} parameter. Static files are handled by Spiffy's
     445default handler.
     446
     447See also {{page-serve-handler}}.
    338448
    339449
     
    352462
    353463
    354 <parameter>pages</parameter>
    355 
    356 An alist of all available pages indexed by their source file names
    357 relative to {{(source-dir)}}. The values are {{page}} records.
    358 
    359 This used to be a constant up until version 0.13.
    360 
    361 
    362 <procedure>(current-page)</procedure>
    363 
    364 Returns the current page's record.
    365 
    366 
    367 <procedure>(page-path #!optional (page (current-page)))</procedure>
    368 
    369 Returns the given {{page}}'s absolute URI path.
    370 
    371 
    372 <procedure>(page-source-path #!optional (page (current-page)))</procedure>
    373 
    374 Returns the given {{page}}'s source path relative to {{(source-dir)}}.
    375 
    376 
    377 <procedure>(page-vars #!optional (page (current-page)))</procedure>
    378 
    379 Returns the given {{page}}'s page-vars as an alist.
    380 
    381 
    382 <procedure>(page-type #!optional (page (current-page)))</procedure>
    383 
    384 Returns the given {{page}}'s type which is one of the following symbols:
    385 
    386 ; dynamic : a page which is handled by one of Hyde's page translators
    387 ; static : a page which is just copied to {{(output-dir)}}
    388 ; directory : a directory
    389 
    390 
    391 <procedure>(read-page page #!rest layouts)</procedure>
    392 
    393 Returns the given {{page}}'s contents, possibly wrapped in the given
    394 {{layouts}}. {{page}} may be either a {{page}} record or a path
    395 relative to {{(source-dir)}}. This procedure is useful to create
    396 aggregate pages. Note that it will translate the contents of dynamic
    397 {{page}}s even if they have not been compiled, yet. In this case, they
    398 will neither be wrapped in page-specific nor the default layouts, only
    399 the ones given in {{layouts}}.
    400 
    401464
    402465<constant>contents</constant>
     
    404467The translated contents of the current page. Only available in layouts.
    405468
    406 === Change Log
    407 
    408 ; 0.16 : Add {{hyde build}} command. Allow link-shortcuts to be procedures. Extract {{pathify}}. Use {{big-chicken}} module environment when possible. Fix issue in {{hyde serve}} with trailing slashes on paths (thanks John J Foerch for the patch). Add {{ignore-page?}}. Fix escaping issue in colorize-code (thanks Peter Bex for the patch). Add a link with relation {{alternate}} to the atom feed emitted by {{hyde-atom}}.
    409 ; 0.15 : Add {{hyde-atom}} module for convenient generation of atom feeds from pages. Export {{sxml-conversion-rules}}
    410 ; 0.14 : Some compatibility changes. Depend on Spiffy >= 4.9.
    411 ; 0.13 : Update to scss 0.3. Make {{pages}} a parameter in {{page-eval-env}}.
    412 ; 0.12 : Add {{link-shortcuts}}.
    413 ; 0.11 : Change {{default-page-vars}} irregex keys to match against {{page-source-path}} instead of {{page-path}}. Add environments. Add {{uri-path-prefix}}.
    414 ; 0.10 : Add colorize support to svnwiki pages. Implement more powerful {{default-page-vars}}. Add {{make-external-translator}} (thanks to Christian Kellermann for the patch). Only recompile requested pages instead of the whole site with {{hyde serve}}.
    415 ; 0.9 : Print usage for unknown commands (thanks to Christian Kellermann). Add current-page binding and make it the default argument for all page record field accessors.
    416 ; 0.8 : Add svnwiki and atom page translators. Make pages a proper type. Allow creation of aggregate pages through {{read-page}}. Drop {{sxml-shortcuts}} from {{sxml-conversion-rules}}.
     469
     470=== Hooks
     471
     472<parameter>around-page-translate</parameter>
     473
     474A procedure that is called for every page translation. It needs to
     475accept the following arguments:
     476
     477; {{page}} : The page being translated
     478; {{translate}} : A thunk which returns the translation result
     479
     480The procedure needs to return the translation result. Default:
     481
     482<enscript language="scheme">
     483(lambda (page translate) (translate))
     484</enscript>
     485
     486Available since version 0.21.0.
     487
     488<parameter>page-serve-handler</parameter>
     489
     490A procedure that is called for every request handled by {{hyde
     491serve}}. It needs to accept the following arguments:
     492
     493; {{page}} : The requested page or {{#f}} if none was found for the requested path
     494; {{path}} : The requested path represented as a list of strings
     495; {{continue}} : A thunk to be called in case no response was sent
     496
     497The procedure should either send a response (e.g. via
     498[[/egg/spiffy|Spiffy]]'s {{send-response}} procedure) or call the
     499{{continu}} thunk. The default is {{serve-page}}.
     500
     501Available since version 0.21.0.
     502
     503=== Version History
     504
     505==== Version 0.21.0
     506
     507* Add {{around-page-translate}} and {{page-serve-handler}} hooks.
     508* Export all page accessors and translators.
     509* As a result of this, remove many bindings from the default {{page-eval-env}} (most notably {{pages}}).
     510* Make {{make-external-translator}} use {{copy-port}} instead of line-wise reading/writing and turn it into a procedure.
     511* Also handle dotfiles (e.g. for .htaccess files, thanks Peter Bex for the suggestion).
     512
     513
     514==== Version 0.20.0
     515
     516* Replace deprecated  [[/egg/environments|environments egg]] with mostly drop-in {{hyde-page-eval-env}} module.
     517
     518==== Version 0.16
     519
     520* Add {{hyde build}} command.
     521* Allow link-shortcuts to be procedures.
     522* Extract {{pathify}}.
     523* Use {{big-chicken}} module environment when possible.
     524* Fix issue in {{hyde serve}} with trailing slashes on paths (thanks John J Foerch for the patch).
     525* Add {{ignore-page?}}. Fix escaping issue in colorize-code (thanks Peter Bex for the patch).
     526* Add a link with relation {{alternate}} to the atom feed emitted by {{hyde-atom}}.
     527
     528==== Version 0.15
     529
     530* Add {{hyde-atom}} module for convenient generation of atom feeds from pages.
     531* Export {{sxml-conversion-rules}}
     532
     533
     534==== Version 0.14
     535
     536* Some compatibility changes. Depend on Spiffy >= 4.9.
     537
     538
     539==== Version 0.13
     540
     541* Update to scss 0.3.
     542* Make {{pages}} a parameter in {{page-eval-env}}.
     543
     544==== Version 0.12
     545
     546* Add {{link-shortcuts}}.
     547
     548==== Version 0.11
     549
     550* Change {{default-page-vars}} irregex keys to match against {{page-source-path}} instead of {{page-path}}.
     551* Add environments.
     552* Add {{uri-path-prefix}}.
     553
     554
     555==== Version 0.10
     556
     557* Add colorize support to svnwiki pages.
     558* Implement more powerful {{default-page-vars}}.
     559* Add {{make-external-translator}} (thanks to Christian Kellermann for the patch).
     560* Only recompile requested pages instead of the whole site with {{hyde serve}}.
     561
     562
     563==== Version 0.9
     564
     565* Print usage for unknown commands (thanks to Christian Kellermann).
     566* Add current-page binding and make it the default argument for all page record field accessors.
     567
     568==== Version 0.8
     569
     570* Add svnwiki and atom page translators.
     571* Make pages a proper type.
     572* Allow creation of aggregate pages through {{read-page}}.
     573* Drop {{sxml-shortcuts}} from {{sxml-conversion-rules}}.
    417574
    418575
     
    425582=== License
    426583
    427   Copyright (c) 2010-2012, Moritz Heidkamp
     584  Copyright (c) 2010-2014, Moritz Heidkamp
    428585  All rights reserved.
    429586 
Note: See TracChangeset for help on using the changeset viewer.