rrthomas / darkglass Goto Github PK

See Reuben for details.

This file is no longer in the top-level directory

# Check we're being run from the right place
if [ ! -f "About DarkGlass.md" ]; then

This isn't particularly good advice. There's no need for the Perl script to have a URL. There's a missed opportunity to sanity-check the URL path (e.g. forbid ".." and " "). And there's no need to mess around with URL rewriting.

The Apache directive I'm thinking of is ScriptAliasMatch. https://docstore.mik.ua/orelly/weblinux2/apache/ch16_05.htm

Already it has enough info to write the value of DocumentRoot.

The docs have been written from the point of view of using DarkGlass as a CGI script. Since it's now possible to use it as a static site generator, there are a few places in the docs where clarification is needed that you are talking about the source files.

In particular, it is confusing to use DocumentRoot to mean the source directory, since that will instead be the build directory.

I don't think it's necessary to change much. Just check every mention of a directory and make the necessary distinction.

It's OK that we have it currently on rrt.sc3d.org, but it would be cleaner and more convincing to have it on GitHub Pages.

1. cv no longer needs to be run with perl
2. Static site fails to run web.pl if path is given as web.pl rather than ./web.pl.

We don't need to support 8.3 filesystems any more.

As of today, Hulot supports converting e.g. text/json to text/html. DarkGlass naively uses this (and the same for application/javascript) and everything breaks. DarkGlass should not (normally) convert MIME types that are used in their own right.

Offer alternate MIME types (anything that can be provided with ?convert) for all content.

They can be written in web.pl for my web site (although currently I'm stuck on an older version of DarkGlass).

See https://www.w3.org/International/questions/qa-when-lang-neg

Add:

• Support for HTTP language negotiation
• Support for multi-language pages: for each page.EXT, check for page.XX.EXT, where XX is a language code. Use LANG (already set) as the default language. Template the lang attribute on html element.
• A language switch, which appears when a page is available in multiple languages.

On every push.

Don't have the program startup in the same file as configuration.

It would also be nice if the config were in a standard format (e.g. .ini), but maybe not immediately, as we'd also like to move the per-site macros to configuration.

One simple way to achieve this would be to move the startup code to the module (i.e. allow it to run as a program), and have that source a config file (given how? probably by environment variable, so it can work from CGI mode too).

Then we have everything we need for a dynamic or static site installed.

Don't forget to update the docs and the update-site script for the docs site!

Problem: URLs with a ? in them don't work for statically generated sites in general. These are currently used by DarkGlass to specify (for example) the target MIME type to convert the file to. A typical URL is file:///blog/README.md?convert=text/html. Consequently, that functionality doesn't work for static sites.

Tentative idea (tires not kicked)

Redefine the URLs without ?s. Remove the query parameter, and add a path component with a file extension corresponding to the MIME type, e.g. file:///blog/README.md/index.html.

$download generates URLs containing ?, which don't work on static sites.

This should be "more compatible" at the Markdown syntax level; it would be nice to offer better syntax colouring. Ideally something that uses Pygments, but see what there is.

Please add to the docs an example of an input directory tree and the corresponding output tree (or URL space). Things to cover:

• Files that get converted to HTML
• Files that have alternative conversions
• Getting the source for a file
• index.html
• style.css

Currently uses the time at which the site was generated!

Static sites should be able to have their HTML files end .html. This is blocking #21.

Currently the URLs are server-relative, which means that a static site (all of whose links will have been rewritten via $url) does not in general work when tested locally. (A workaround is to run a development server.)

web.pl.=*.md is garbled.

"macro" link is broken.

I was hoping that this "organisation" page would show me how to structure my source files and how the built files will come out, but it doesn't.

Ideally this would be in %Macros along with everything else.

Also $file.

• Converting/generating file types. (A thin layer on top of Hulot.)
• Rendering HTML pages with macro expansion. (A thin layer on top of Macro.pm.)
• Serving the resultant file.

Once this is done, it should be possible to start rewriting the parts in Python, for greater sanity.

Only the first two parts are needed for static sites!

E.g. web.pl: Can't exec "makepage": No such file or directory at MIME/Convert.pm line 142..

We don't use doc-installed.

Needed e.g. for #20.

This is hard to do before DarkGlass is rewritten in Python, as the code needs to run in DarkGlass context, or the converters need to be supplied with a lot of extra information somehow.

This was last working a long time ago. There was a problem because the UIDs for the feed items were generated arbitrarily each time, causing some readers to think that all articles were new each time the feed was generated; hence, should change the UIDs to depend on the article (e.g. generate from filename + timestamp).