stencilproject/Stencil

Documentation out of date

KingOfBrian opened this issue · 4 comments

KingOfBrian commented

Just learning stencil, and I noticed that a lot of the docs are out of date. I don't know the language very well, so I'm not the best to audit it, but I ran into these two issues:

http://stencil.fuller.li/en/latest/builtins.html

  • elif is not a valid expresion
  • The for expression does not set so variables inside the loop, but are available via forloop.last etc.
kylef commented

Can I just confirm which version of Stencil you are running @KingOfBrian ?

KingOfBrian commented

Ah sorry about that, good catch -- 0.8. Looks like 0.9 adds the elif support. No note on forloop.last though. Close if out if it reflects 0.9 properly.

bladebunny commented

The documentation also shows creating paths and extensions via string arrays, but it seems those have been replaced by "Path" and "Extension" types. Very confusing. I'm sure I'll sort it out but pretty frustrating. Especially as "Path" is not even a type from Stencil but rather seems to come from "PathKit". Not sure I understand the decision to not use Foundation types for file system objects. Was this for cross platform compatibility? Anyway, the library seems to have a lot of potential so I am forging on.

kylef commented

@bladebunny Path is string convertible so you can provide strings directly where Path is allowed, which is what the documentation does. You may need to import PathKit.

Was this for cross platform compatibility?

Yes, and to encapsulate the file reading/writing. When this was written Open Foundation was rather incomplete and raised fatalErrors because features were missing.

decision to not use Foundation types for file system objects

You may also use Foundation types if you desire, you can pass in a URL from foundation.

Sources/Template.swift:  public convenience init(URL:Foundation.URL) throws {