Shortcodes: Update readfile to throw compile error when file not found

[aimeeu]

• Update the readfile shortcode to throw a compile error when the file is not found.
• Update userguide

Currently the shortcode prints a message on the UI, which presents a problem when refactoring a docs site. A UI message requires visual conformation and is easy to miss when moving or renaming directories. Throwing a compile error ensures the tech writer knows there is a problem.

With this modification, the default behavior is to throw a compile error:

Alternately, the user can display a message on the page instead of having Hugo throw a compile error (this implements deining's suggestion)

[aimeeu]

@LisaFC can someone review this please?

[LisaFC]

Looks fine to me, but @geriom can you take a look as you wrote the original shortcode?

[deining]

A UI message requires visual conformation and is easy to miss when moving or renaming directories.

I see the point, and yes, I consider this PR an improvement and agree that throwing a compile error should be made the default behaviour. However, I can imagine situations where throwing a compile error is unwanted (e.g. with draft documents). What about adding and evaluating a shortcode parameter draft? With attribute draft set to true, the current behaviour (printing out an error message in the code) would apply. This way, one could author:

{{< readfile draft=true >}}
...
{{< /readfile >}}

Without parameter draft, a compile error would be thrown.

Just my tow cents ....

[geriom]

LGTM. Thank you!