webgen users - Oct 2008 - Webgen Bug, Maruku Bug, Questions, Suggestions

> I found out that it doesn''t parse this simple example:
>
> before text
> +--
> this should become a div
> =--
> after text
>
> I posted this on Maruku Rubyforge one month ago and also sent an email to
> Andrea, but he hasn''t responded since then. Is Maruku still
developed
> actively?
When I have the time :-(


--
Andrea Censi
PhD student, Control & Dynamical Systems, Caltech
http://www.cds.caltech.edu/~andrea/
    "Life is too important to be taken seriously" (Oscar Wilde)

Webgen Bug
----------

I''ve detected a bug in Webgen/Maruku. If you declare two 
headers with the same name, like this

##Animals
###Animals

webgen stops with

undefined meththod `[]='' for nil:NilClass

Speaking of Maruku...



Maruku Bug
----------

I found out that it doesn''t parse this simple example:

before text
+--
this should become a div
=--
after text

I posted this on Maruku Rubyforge one month ago and also 
sent an email to Andrea, but he hasn''t responded since then. 
Is Maruku still developed actively?



Feed Question
-------------

I would like to create feeds, but I''m not sure how to write 
it, even after reading the documentation of 
Webgen::SourceHandler::Feed. Can you give an example for the 
`entries` metainfo key when specifying a set of files? Is it 
possible to create the feed from other blocks than `content`?


Webgen::SourceHandler::Copy Question
------------------------------------

How can I teach this Sourcehandler to copy also files like 
*.php or *.htc?


Suggestions
-----------

I worked extensively with Webgen in the last months. There 
are a few suggestions I have for future features. Currently, 
I worked around the following issues with Bash pre- and 
postprocessing.

*  If a link is set to the current page via Maruku syntax, 
then a link is displayed even if 
website.link_to_current_page is set to true in config.yaml. 
Ideally, this shouldn''t be.

*  I was in a situation where I had both files and 
subdirectories in a menu, and I wanted two separate menus 
for the files and the directories. Maybe it would have its 
uses to distinguish in tag.menu.used_nodes: between files 
and directories.



Thanks a lot,
Michael

> *  If a link is set to the current page via Maruku syntax, then a link 
> is displayed even if website.link_to_current_page is set to true in 
> config.yaml. Ideally, this shouldn''t be.
Correction:

website.link_to_current_page is set to FALSE

> Webgen Bug
> ----------
> 
> I''ve detected a bug in Webgen/Maruku. If you declare two 
> headers with the same name, like this
> 
> ##Animals
> ###Animals
> 
> webgen stops with
> 
> undefined meththod `[]='' for nil:NilClass
Okay, there are two problems here:

1. Maruku should not generate the same id attribute here because id
attributes have to be unique in one file.
2. It''s nonetheless a bug in webgen which I will investigate. However,
in the development version this part has changed, so it may take some
time to fix this.

As a work around you can do the following:

## Animals {: #animals1}
### Animals {: #animals2}
> Feed Question
> -------------
> 
> I would like to create feeds, but I''m not sure how to write 
> it, even after reading the documentation of 
> Webgen::SourceHandler::Feed. Can you give an example for the 
> `entries` metainfo key when specifying a set of files? Is it 
> possible to create the feed from other blocks than `content`?
This is the feed file used by the webgen website:

    ---
    title: Webgen News
    description: webgen - static website generation made easy
    site_url: http://webgen.rubyforge.org/
    author: Thomas Leitner
    author_url: http://webgen.rubyforge.org
    number_of_entries: 10
    rss: false
    entries: [rel*.html]
So, entries has to be an array of LCNs patterns.

It is currently not possible to use any other block since the name is
hard coded. However, if you need this I could provide support for an
additional option for specifying the block name.
> Webgen::SourceHandler::Copy Question
> ------------------------------------
> 
> How can I teach this Sourcehandler to copy also files like 
> *.php or *.htc?
Have a look at
http://webgen.rubyforge.org/documentation/manual.html#website-configfile
- especially the patterns configuration helper.
> Suggestions
> -----------
> 
> I worked extensively with Webgen in the last months. There 
> are a few suggestions I have for future features. Currently, 
> I worked around the following issues with Bash pre- and 
> postprocessing.
> 
> *  If a link is set to the current page via Maruku syntax, 
> then a link is displayed even if 
> website.link_to_current_page is set to true in config.yaml. 
> Ideally, this shouldn''t be.
Could you please show me an example of this syntax? You are using the
relocatable tag, aren''t you? If you use

    This is a [link]({relocatable: ../some_file.html}) to a page.

then the relocatable tag only returns the correct relative path and
Maruku generates the link. So there is no way for webgen to interfere
with the link creation. However, a link tag will possibly appear in one
of the next version which could solve this problem.
> *  I was in a situation where I had both files and 
> subdirectories in a menu, and I wanted two separate menus 
> for the files and the directories. Maybe it would have its 
> uses to distinguish in tag.menu.used_nodes: between files 
> and directories.
Okay, will think about that. Thanks!

-- Thomas

>> I posted this on Maruku Rubyforge one month ago and also sent an email
to
>> Andrea, but he hasn''t responded since then. Is Maruku still
developed
>> actively?
> 
> When I have the time :-(
Ok, thanks. I just thought that when it is in the 
documentation, it should do it.

> As a work around you can do the following:
> 
> ## Animals {: #animals1}
> ### Animals {: #animals2}
Thanks for this!

>     entries: [rel*.html]
> So, entries has to be an array of LCNs patterns.
*   Ok, now I understand that `pattern` means the wildcard 
in the example above. And an array of those patterns would 
be for example:

     entries: [a*.html, dir1/*.html]

which works.


* But I notice that it is not possible to include single 
files. Would it be possible to do that:

     entries: [a.html]
or
     entries: [dir1/b.html, dir1/sub/c.html]


* After trial and error I found out that entries get sorted 
after the key `modified_at:` AND the time format has to be 
ISO-8601, else it is ignored. Maybe you could document this 
for other users.


* I found out that it makes no difference in the rendered 
atom/rss file if the key `created_at:` is declared in the 
source .feed file or not. The time is nowhere to be found.


* After declaring the `icon:` key like this

     icon: /images/icon.png

or trial-and-error variants of this, webgen stops with the 
following error:

     An error has occurred:   Error while processing 
</feed.atom>: undefined method `path'' for nil:NilClass

> It is currently not possible to use any other block since the name is
> hard coded. However, if you need this I could provide support for an
> additional option for specifying the block name.
My page files consist of the `content` block, which contains 
a large amount of content (say, 20-30 real pages of text) 
and a `abstract` block, which contains only 1-2 paragraphs 
as summary. It would be nice if this `abstract` block could 
be used in a <description> block of the feed. This paragraph 
would be displayed below the link, if users click on the RSS 
icon.

To include the large body of text would IMO be of no use for 
feed purposes (and with 10 articles, the feed would get very 
large, about 500kB)

>> *  If a link is set to the current page via Maruku syntax, 
>> then a link is displayed even if 
>> website.link_to_current_page is set to true in config.yaml. 
>> Ideally, this shouldn''t be.
> 
> Could you please show me an example of this syntax? You are using the
> relocatable tag, aren''t you?
Correct.


If you use
> 
>     This is a [link]({relocatable: ../some_file.html}) to a page.
> 
> then the relocatable tag only returns the correct relative path and
> Maruku generates the link. So there is no way for webgen to interfere
> with the link creation. However, a link tag will possibly appear in one
> of the next version which could solve this problem.
This link tag would be useful, since links to the current 
page are seldom desirable IMO. I would need this, because 
I''m automatically (via sed) setting cross-reference links 
for terms that need explanation to a glossary. And the 
glossary needs to be excluded from the links to the glossary ;)


Thanks for your help.

Michael

> * But I notice that it is not possible to include single 
> files. Would it be possible to do that:
> 
>      entries: [a.html]
> or
>      entries: [dir1/b.html, dir1/sub/c.html]
It is possible but remember that it is a LCN pattern and not a CN
pattern - so you need to do something like

    entries: [a.en.html]
or
    entries: [dir1/b.en.html, dir1/sub/c.en.html]

(substitute en with the approriate language code).
 
> * After trial and error I found out that entries get sorted 
> after the key `modified_at:` AND the time format has to be 
> ISO-8601, else it is ignored. Maybe you could document this 
> for other users.
I have updated the feed documentation, thanks for the hint!

The `modified_at` meta information is derived from the file modification
time and can be overwritten in a page file or using metainfo files.
However, both the meta information block of a page file and the
metainfo files use YAML and therefore you need to use the time format
specified by YAML. If the specified value is not correct, the current
time is used as modified_at value.

I have also updated the meta information reference page with links to
the YAML timestamp specification.
> * I found out that it makes no difference in the rendered 
> atom/rss file if the key `created_at:` is declared in the 
> source .feed file or not. The time is nowhere to be found.
The value for the key also needs to be a valid YAML timestamp including
the time part and is used for the publication date of the feed. Looking
through the sources of the feed_tools library which is used for
generating the feeds I found that the publication date is only used for
RSS 2.0 feeds.
> * After declaring the `icon:` key like this
> 
>      icon: /images/icon.png
> 
> or trial-and-error variants of this, webgen stops with the 
> following error:
> 
>      An error has occurred:   Error while processing 
> </feed.atom>: undefined method `path'' for nil:NilClass
You would need to specify the absolute localized canonical name of the
icon you wish to use. Your example looks right to me and in tests this
works. However, I have just noticed the feed_tools version doesn''t
support setting the feed icon so I will remove support for this option.
 
> > It is currently not possible to use any other block since the name
> > is hard coded. However, if you need this I could provide support
> > for an additional option for specifying the block name.
> 
> My page files consist of the `content` block, which contains 
> a large amount of content (say, 20-30 real pages of text) 
> and a `abstract` block, which contains only 1-2 paragraphs 
> as summary. It would be nice if this `abstract` block could 
> be used in a <description> block of the feed. This paragraph 
> would be displayed below the link, if users click on the RSS 
> icon.
> 
> To include the large body of text would IMO be of no use for 
> feed purposes (and with 10 articles, the feed would get very 
> large, about 500kB)
Okay, I have added an option `content_block_name` for specifying the
block that should be used. Be aware that all page files that can
appear in a feed need to have such a block!
 
> If you use
> > 
> >     This is a [link]({relocatable: ../some_file.html}) to a page.
> > 
> > then the relocatable tag only returns the correct relative path and
> > Maruku generates the link. So there is no way for webgen to
> > interfere with the link creation. However, a link tag will possibly
> > appear in one of the next version which could solve this problem.
> 
> This link tag would be useful, since links to the current 
> page are seldom desirable IMO. I would need this, because 
> I''m automatically (via sed) setting cross-reference links 
> for terms that need explanation to a glossary. And the 
> glossary needs to be excluded from the links to the glossary ;)
I have the link tag on my todo list. It will output basically the same
links as the menu or breadcrumb_trail tags. So even if not linking
to the current page, the link title is still displayed.

-- Thomas

>     entries: [dir1/b.en.html, dir1/sub/c.en.html]
Works! I''m not using languages, so I thought it wouldn''t be 
necessary.
> The value for the key also needs to be a valid YAML timestamp including
> the time part and is used for the publication date of the feed. Looking
> through the sources of the feed_tools library which is used for
> generating the feeds I found that the publication date is only used for
> RSS 2.0 feeds.
Would it be possible to use RSS 2.0 feeds? Not important for 
me, just asking.

>> My page files consist of the `content` block, which contains 
>> a large amount of content (say, 20-30 real pages of text) 
>> and a `abstract` block, which contains only 1-2 paragraphs 
>> as summary. It would be nice if this `abstract` block could 
>> be used in a <description> block of the feed. This paragraph 
>> would be displayed below the link, if users click on the RSS 
>> icon.
> Okay, I have added an option `content_block_name` for specifying the
> block that should be used. Be aware that all page files that can
> appear in a feed need to have such a block!
Do you mean an config.yaml option? Can you help me out where 
  to put it and how to write it?

Does webgen put the content of the specified block in the 
RSS/ATOM <description> or <content> tag?

Michael

> > The value for the key also needs to be a valid YAML timestamp
> > including the time part and is used for the publication date of the
> > feed. Looking through the sources of the feed_tools library which
> > is used for generating the feeds I found that the publication date
> > is only used for RSS 2.0 feeds.
> 
> Would it be possible to use RSS 2.0 feeds? Not important for 
> me, just asking.
I can see if I can do that easily and if so, it will be in the next
release.
> >> My page files consist of the `content` block, which contains 
> >> a large amount of content (say, 20-30 real pages of text) 
> >> and a `abstract` block, which contains only 1-2 paragraphs 
> >> as summary. It would be nice if this `abstract` block could 
> >> be used in a <description> block of the feed. This paragraph
> >> would be displayed below the link, if users click on the RSS 
> >> icon.
> 
> > Okay, I have added an option `content_block_name` for specifying the
> > block that should be used. Be aware that all page files that can
> > appear in a feed need to have such a block!
> 
> Do you mean an config.yaml option? Can you help me out where 
>   to put it and how to write it?
It will be an option that needs to be put into the .feed file, like
entries. The name is as I have written it: content_block_name. However,
the changes regarding the feed handler are currently only in my local
repo, will be pushed to the github/rubyforge one soon (probably on
Sundary).
 
> Does webgen put the content of the specified block in the 
> RSS/ATOM <description> or <content> tag?
It puts the content in the content tag.

-- Thomas

> It will be an option that needs to be put into the .feed file, like
> entries. The name is as I have written it: content_block_name. However,
> the changes regarding the feed handler are currently only in my local
> repo, will be pushed to the github/rubyforge one soon (probably on
> Sundary).
Ok, thanks!

Another suggestion regarding feeds:

The feed entries are sorted by the metainfo `modified_at` 
from older dates to recent dates. But the most feeds I saw 
sort them in the reverse direction, recent entries first. If 
users bookmark the feed in their browser, for example, it 
would be intuitive that the recent articles are located at 
the top.

FWIW,

Michael