From 190964c57bdd81ef1c0b7bf518c0a2b678794bcf Mon Sep 17 00:00:00 2001 From: Anthony Fok Date: Thu, 8 Jan 2015 18:21:04 -0700 Subject: [PATCH] [Docs] New Troubleshooting section With two entries of frequently encountered or obscured troubles so far: - "Categories with accented characters" Unicode NFC/NFD mismatch on Mac OS X (See #739) - `hugo new` aborts with cryptic EOF error (See #776) --- docs/config.toml | 12 +++-- .../categories-with-accented-characters.md | 49 +++++++++++++++++++ .../troubleshooting/strange-eof-error.md | 42 ++++++++++++++++ 3 files changed, 99 insertions(+), 4 deletions(-) create mode 100644 docs/content/troubleshooting/categories-with-accented-characters.md create mode 100644 docs/content/troubleshooting/strange-eof-error.md diff --git a/docs/config.toml b/docs/config.toml index 90dc3601e..b6af1635e 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -51,10 +51,6 @@ MetaDataFormat = "yaml" name = "extras" pre = "" weight = -60 -[[menu.main]] - name = "tutorials" - pre = "" - weight = -40 [[menu.main]] name = "community" pre = "" @@ -64,3 +60,11 @@ MetaDataFormat = "yaml" name = "Discussion Forum" url = "http://discuss.gohugo.io" weight = 150 +[[menu.main]] + name = "tutorials" + pre = "" + weight = -40 +[[menu.main]] + name = "troubleshooting" + pre = "" + weight = -30 diff --git a/docs/content/troubleshooting/categories-with-accented-characters.md b/docs/content/troubleshooting/categories-with-accented-characters.md new file mode 100644 index 000000000..879c7519a --- /dev/null +++ b/docs/content/troubleshooting/categories-with-accented-characters.md @@ -0,0 +1,49 @@ +--- +date: 2015-01-08T16:32:00-07:00 +menu: + main: + parent: troubleshooting +title: Accented Categories +weight: 10 +--- + +## Trouble: Categories with accented characters + +One of my categories is named "Le-carré," but the link ends up being generated like this: + + categories/le-carr%C3%A9 + +And not working. Is there an easy fix for this that I'm overlooking? + + +## Solution + +Mac OS X user? If so, you are likely a victim of HFS Plus file system's insistence to store the "é" (U+00E9) character in Normal Form Decomposed (NFD) mode, i.e. as "e" + " ́" (U+0065 U+0301). + +`le-carr%C3%A9` is actually correct, `%C3%A9` being the UTF-8 version of U+00E9 as expected by the web server. Problem is, OS X turns [U+00E9] into [U+0065 U+0301], and thus `le-carr%C3%A9` no longer works. Instead, only `le-carre%CC%81` ending with `e%CC%81` would match that [U+0065 U+0301] at the end. + +This is unique to OS X. The rest of the world does not do this, and most certainly not your web server which is most likely running Linux. This is not a Hugo-specific problem either. Other people have been bitten by this when they have accented characters in their HTML files. + +Nor is this problem specific to Latin scripts. Japanese Mac users often run into the same issue, e.g. with `だ` decomposing into `た` and ゙.[^1] + +Rsync 3.x to the rescue! From [an answer posted on Server Fault](http://serverfault.com/questions/397420/converting-utf-8-nfd-filenames-to-utf-8-nfc-in-either-rsync-or-afpd): + +> You can use rsync's `--iconv` option to convert between UTF-8 NFC & NFD, at least if you're on a Mac. There is a special `utf-8-mac` character set that stands for UTF-8 NFD. So to copy files from your Mac to your web server, you'd need to run something like: +> +> `rsync -a --iconv=utf-8-mac,utf-8 localdir/ mywebserver:remotedir/` +> +> This will convert all the local filenames from UTF-8 NFD to UTF-8 NFC on the remote server. The files' contents won't be affected. + +Please make sure you have the latest version rsync 3.x installed. The rsync that ships with OS X (even the latest 10.10 Yosemite) is the horribly old at version 2.6.9 protocol version 29. The `--iconv` flag is new in rsync 3.x. + +### References + +* http://discuss.gohugo.io/t/categories-with-accented-characters/505 +* [Converting UTF-8 NFD filenames to UTF-8 NFC, in either rsync or afpd](http://serverfault.com/questions/397420/converting-utf-8-nfd-filenames-to-utf-8-nfc-in-either-rsync-or-afpd) (Server Fault) +* http://wiki.apache.org/subversion/NonNormalizingUnicodeCompositionAwareness +* https://en.wikipedia.org/wiki/Unicode_equivalence#Example +* http://zaiste.net/2012/07/brand_new_rsync_for_osx/ +* https://gogo244.wordpress.com/2014/09/17/drived-me-crazy-convert-utf-8-mac-to-utf-8/ + + +[^1]: As explained in the Japanese Perl Users article [Encode::UTF8Mac makes you happy while handling file names on MacOSX](http://perl-users.jp/articles/advent-calendar/2010/english/24). diff --git a/docs/content/troubleshooting/strange-eof-error.md b/docs/content/troubleshooting/strange-eof-error.md new file mode 100644 index 000000000..55a5cb496 --- /dev/null +++ b/docs/content/troubleshooting/strange-eof-error.md @@ -0,0 +1,42 @@ +--- +date: 2015-01-08T16:11:23-07:00 +menu: + main: + parent: troubleshooting +title: Strange EOF error +weight: 5 +--- + +## Trouble: `hugo new` aborts with cryptic EOF error + +I'm running into an issue where I cannot get archetypes working, when running `hugo new showcase/test.md`, for example, I see an `EOF` error thrown by Hugo. + +I have set up this test repository to show exactly what I've done, but it is essentially a vanilla installation of Hugo. https://github.com/polds/hugo-archetypes-test + +When in that repository, using Hugo v0.12 to run `hugo new -v showcase/test.md`, I see the following output: + + INFO: 2015/01/04 Using config file: /private/tmp/test/config.toml + INFO: 2015/01/04 attempting to create showcase/test.md of showcase + INFO: 2015/01/04 curpath: /private/tmp/test/archetypes/showcase.md + ERROR: 2015/01/04 EOF + +Is there something that I am blatantly missing? + +## Solution + +Thank you for reporting this issue. The solution is to add a final newline (or EOL) to the end of your default.md archetype file of your theme. More discussions happened on the forum here: + +* http://discuss.gohugo.io/t/archetypes-not-properly-working-in-0-12/544 +* http://discuss.gohugo.io/t/eol-f-in-archetype-files/554 + +So yes, we do need to fix this. We need to do the following: + +1. Add warnings about this in the Hugo documentation, as several people have run into the same problem already. (Users of editors like Vim, nano and gedit are immune to this because these editors enforce an EOL at the end of the file by default, but other editors like Emacs don't do that.) +2. Improve the error message. It is difficult to determine what went wrong with just three characters "`EOF`" +3. Allow archetype files without the final EOL to compile anyway, but do give an appropriate and detailed warning. (optional, to be discussed) +https://github.com/spf13/hugo/issues/776 + +## References + +* https://github.com/spf13/hugo/issues/776 +