Improve documentation.

FossilOrigin-Name: 45daa736416368f7ea06099c6376669f855fe257459825468cac4b59a3333888

TO-DO.adoc

@@ -1,6 +1,6 @@
 = Fendo TO-DO
 :author: Marcos Cruz (programandala.net)
-:revdate: 2018-12-17
+:revdate: 2018-12-20
 
 // This text file is in Asciidoctor format
 // See http://asciidoctor.org
@@ -217,8 +217,8 @@ http://www.blogger.com/blog_this.pyra?t=&u=http%3A%2F%2Fwww.iconarchive.com%2Fsh
 
 Check:
 
-`link_text_as_attribute?` is the condition of an unbalanced `[if]` in <fendo.links.fs>.
-It has been fixed, but it has to be tested.
+`link_text_as_attribute?` is the condition of an unbalanced `[if]` in
+<fendo.links.fs>.  It has been fixed, but it has to be tested.
 
 Idea:
 
@@ -523,3 +523,32 @@ NOTE: Milestone: 0.7.0:
 NOTE: Milestone: 0.6.0:
 
 - Rename `content` to `echo_content`.
+
+== 2018-12-19
+
+NOTE: Milestone: 0.6.0:
+
+- Fix: <fendo.addon.atom.fs> depends on `current_lang$`, which is
+  defined in <fendo.addon.multilingual.fs>.
+
+== 2018-12-20
+
+NOTE: Milestone: 0.6.0:
+
+- Fix: "invalid memory" errors arised trying to access empty fields in
+  two websites.  No error pattern found. The errors vanished when the
+  fields were defined in <fendo.data.fs> instead of the website
+  applications. Maybe it has to do with with initialization of dynamic
+  strings, but `datum:` was used in both cases.
+- Make metadata fields more versatile, e.g. add a variant to accept
+  strings. This way, long strings could be used with `s"" ... ""`.
+- Improve <fendo.addon.atom.fs> to add the full page contents, or
+  until a conventional mark included in the page.
+- Rename `link_text?!`. Perhasp `?link_text!`.
+- Improve: `pid#>lang#` uses  "_language", i.e. it forces the naming
+  of language numerical IDs. Fix this by creating a language defining
+  word.
+- Fix: `hierarchy_navigation_link` creates a list item. It should
+  create only a link. The layout should depend on the application.
+- Update locals notation `pid` to `pageID`.
+- Update stack notation _pid_ to _a_.

VERSION.fs

@@ -3,7 +3,7 @@
 \ This file is part of Fendo
 \ (http://programandala.net/en.program.fendo.html).
 
-: fendo_version ( -- ca len ) s" 0.6.0-pre.29+201812201913" ;
+: fendo_version ( -- ca len ) s" 0.6.0-pre.30+201812201918" ;
 
 \ vim: filetype=gforth
 

doc_src/manual_skeleton.adoc

@@ -1,6 +1,6 @@
 = Fendo %VERSION%
 :author: Marcos Cruz (programandala.net)
-:revdate: 2018-12-07
+:revdate: 2018-12-20
 :toc:
 :toclevels: 1
 :toc-placement!:
@@ -21,6 +21,45 @@ include::../README.adoc[tags=status]
 
 // =============================================================
 
+== Page hierarchy
+
+By default, the page hierarchy is defined by the the source page
+filename, using the dot as a separator.  For example, a source page
+filename <en.articles.2010.fs> has three levels of hierarchy:
+
+1. 'en' = main "section": English pages of the website.
+2. 'articles' = Articles section of the English website.
+3. '2010' = Section of articles of year 2010.
+
+Of course, 'fs' is the filename extension of the Forth source, and it
+does not belongs to the page name.
+
+By default, the corresponding target page will be
+<en.articles.2010.html>.
+
+// XXX TODO -- Complete.
+
+== Multilingual websites
+
+Multilingual websites are built by 
+
+1. Define the number of languages and their identifiers.
+2. Set the language of the pages.
+3. Set the links between page translastions.
+
+The language ID can be any string, usually its corresponding ISO 639-1
+(2-letter) code, ISO 639-2 (3-letter) code, or the name of the
+language. The language ID is used also as the first part (prefix) of
+the page's filename, e.g.:
+
+....
+en.section.subsection.html
+es.sección.subsección.html
+eo.fako.subfako.html
+....
+
+// XXX TODO -- Complete.
+
 == Glossary
 
 

fendo.addon.hierarchy_meta_links.fs

@@ -5,7 +5,7 @@
 
 \ This file is the hierarchy meta links addon.
 
-\ Last modified 201812172116.
+\ Last modified 201812201724.
 \ See change log at the end of the file.
 
 \ Copyright (C) 2013,2014,2015,2017,2018 Marcos Cruz (programandala.net)
@@ -42,16 +42,27 @@
 \   ." Stack at the end of `proper_hierarchical_link? : " .s cr \ XXX INFORMER
 \   key drop \ XXX INFORMER
     ;
+
+  \ doc{
+  \
+  \ proper_hierarchical_link? ( ca len -- ca' len' f )
+  \
   \ If page ID _ca len_ is a proper hierarchical link (i.e., not a
   \ draft page), _f_ is true and _ca' len'_ is its equivalent
-  \ unshortcut page ID; otherwise _f_ is false and _ca' len'_ is
+  \ `unshortcut` page ID; otherwise _f_ is false and _ca' len'_ is
   \ unimportant.
   \
   \ This check is required in order to bypass the default behaviour of
   \ links: a link to a draft local page simply prints the link text,
   \ but that is not convenient for the hierarchy meta links.  This
   \ check can be used also by the application, as part of the user's
   \ hierarchy navigation bar.
+  \
+  \ ``proper_hierarchical_link?`` is used by `hierarchical_meta_link`.
+  \
+  \ See: `hierarchical_meta_links`, `pid$>draft?`.
+  \
+  \ }doc
 
 : (hierarchy_meta_link) ( ca1 len1 ca2 len2 -- )
 \  cr 2dup type ."  --> " 2over type  \ XXX INFORMER
@@ -65,9 +76,19 @@
   dup title unmarkup title=!
   ?hreflang=!  s" text/html" type=!
   [<link/>] ;
-  \ Create a hierarchy meta link in the HTML header.
-  \ ca1 len1 = page ID
-  \ ca2 len2 = rel
+
+  \ doc{
+  \
+  \ (hierarchy_meta_link) ( ca1 len1 ca2 len2 -- )
+  \
+  \ Create a hierarchy meta link to page ID _ca2 len2_,
+  \ with ``rel`` attribute _ca1 len2_.
+  \
+  \ ``(hierarchy_meta_link)`` is a factor of `hierarchy_meta_link`.
+  \
+  \ See: `[<link/>]`.
+  \
+  \ }doc
 
 : hierarchy_meta_link ( ca1 len1 ca2 len2 -- )
 \   ." Stack in `hierarchy_meta_link` : " .s cr  \ XXX INFORMER
@@ -77,9 +98,33 @@
 \   ." Stack in `hierarchy_meta_link` after `proper_hierarchical_link?` : " .s cr  \ XXX INFORMER
 \   key drop \ XXX INFORMER
   if  2swap (hierarchy_meta_link)  else  2drop 2drop  then ;
-  \ Create a hierarchy meta link in the HTML header, if needed.
-  \ ca1 len1 = rel
-  \ ca2 len2 = page ID
+
+  \ doc{
+  \
+  \ hierarchy_meta_link ( ca1 len1 ca2 len2 -- )
+  \
+  \ If needed, create a hierarchy meta link to page ID _ca2 len2_,
+  \ with ``rel`` attribute _ca1 len2_.
+  \
+  \ Usage example in the HTML template:
+
+  \ ----
+  \ <head>
+  \ <title>Page 1</title>
+  \ <[
+  \   s" prev" s" page_0" hierarchy_meta_link
+  \   s" next" s" page_2" hierarchy_meta_link
+  \ ]>
+  \ </head>
+  \ ----
+
+  \ ``hierarchy_meta_link`` is needed only in special cases.
+  \ `hierarchy_meta_links` can be used instead to create all
+  \ hierarchical links automatically.
+  \
+  \ See: `(hierarchy_meta_link)`.
+  \
+  \ }doc
 
 : hierarchy_meta_links ( -- )
 \  s" up" current_page upper_page hierarchy_meta_link
@@ -88,10 +133,31 @@
 \  s" first" current_page first_page hierarchy_meta_link
 \  s" last" current_page last_page hierarchy_meta_link
   ;
-  \ Create the required hierarchy meta links in the HTML header.
+
   \ XXX TMP 2015-02-26: it seems "up", "first" and "last" are not allowed
   \ in <link>; I comment them out.
 
+  \ doc{
+  \
+  \ hierarchy_meta_links ( -- )
+  \
+  \ Create the hierarchy meta links in the HTML header.
+  \
+  \ NOTE: Only "next" and "prev" are created. "up", "first" and "last"
+  \ are not allowed in HTML ``<link>`` tag.
+  \
+  \ Usage example in the HTML template:
+  \
+  \ ----
+  \ <head>
+  \ <[ hierarchy_meta_links ]>
+  \ </head>
+  \ ----
+  \
+  \ See: `hierarchy_meta_link`.
+  \
+  \ }doc
+
 .( fendo.addon.hierarchy_meta_links.fs compiled) cr
 
 \ ==============================================================
@@ -142,5 +208,7 @@
 \ 2018-12-08: Update notation of page IDs in comments and strings.
 \
 \ 2018-12-17: Update: replace `pid$>data>pid#` with `pid$>pid#`.
+\
+\ 2018-12-20: Improve documentation.
 
 \ vim: filetype=gforth

fendo.addon.hierarchy_navigation_links.fs

@@ -5,7 +5,7 @@
 
 \ This file is the hierarchy navigation links addon.
 
-\ Last modified 201812080157.
+\ Last modified 201812201820.
 \ See change log at the end of the file.
 
 \ Copyright (C) 2017,2018 Marcos Cruz (programandala.net)
@@ -35,8 +35,89 @@ defer previous$ ( -- ca len )
 defer next$ ( -- ca len )
 defer up$ ( -- ca len )
 defer last$ ( -- ca len )
-  \ Strings that must be defined by the application.  `l10n-string` or
-  \ `noname-l10n-string` can be used for multilingual sites.
+
+  \ doc{
+  \
+  \ first$ ( -- ca len )
+  \
+  \ A word defined by ``defer``. It must be configured by the
+  \ application in order to return a string _ca len_ containing
+  \ "First" in the language of the current page.
+  \
+  \ Usage example in a monolingual, English-only website:
+
+  \ ----
+  \ :noname s" First" ; is first$
+  \ ----
+
+  \ Usage example in a multilingual website:
+
+  \ ----
+  \ s" Primera" \ Spanish
+  \ s" Unua"    \ Esperanto
+  \ s" First"   \ English
+  \ noname-l10n-string is first$
+  \ ----
+
+  \ See: `previous$`, `next$`, `up$`, `last$`, `noname-l10n-string`.
+  \
+  \ }doc
+
+  \ doc{
+  \
+  \ previous$ ( -- ca len )
+  \
+  \ A word defined by ``defer``. It must be configured by the
+  \ application in order to return a string _ca len_ containing
+  \ "Previous" in the language of the current page.
+  \
+  \ See `first$` for a usage example.
+  \
+  \ See: `next$`, `up$`, `last$`.
+  \
+  \ }doc
+
+  \ doc{
+  \
+  \ next$ ( -- ca len )
+  \
+  \ A word defined by ``defer``. It must be configured by the
+  \ application in order to return a string _ca len_ containing "Next"
+  \ in the language of the current page.
+  \
+  \ See `first$` for a usage example and related words.
+  \
+  \ See: `previous$`, `up$`, `last$`.
+  \
+  \ }doc
+
+  \ doc{
+  \
+  \ up$ ( -- ca len )
+  \
+  \ A word defined by ``defer``. It must be configured by the
+  \ application in order to return a string _ca len_ containing
+  \ "Up" in the language of the current page.
+  \
+  \ See `first$` for a usage example and related words.
+  \
+  \ See: `previous$`, `next$`, `last$`.
+  \
+  \ }doc
+
+  \ doc{
+  \
+  \ last$ ( -- ca len )
+  \
+  \ A word defined by ``defer``. It must be configured by the
+  \ application in order to return a string _ca len_ containing
+  \ "Last" in the language of the current page.
+  \
+  \ See `first$` for a usage example and related words.
+  \
+  \ See: `previous$`, `next$`, `up$`.
+  \
+  \ }doc
 
 : (hierarchy_navigation_link)  ( ca1 len1 ca2 len2 -- )
   2swap s" <span class=`br`>" 2swap s+
@@ -97,5 +178,7 @@ defer last$ ( -- ca len )
 \ `?upper_page`.
 \
 \ 2018-12-08: Update notation of Forth words in comments and strings.
+\
+\ 2018-12-20: Improve documentation.
 
 \ vim: filetype=gforth