Quellcode durchsuchen

fix main smd command implementation

update both readme files to reflect latest state
cdelorme vor 7 Jahren
Ursprung
Commit
19408daa43
3 geänderte Dateien mit 37 neuen und 116 gelöschten Zeilen
  1. 7 7
      cmd/smd/main.go
  2. 9 44
      cmd/smd/readme.md
  3. 21 65
      readme.md

+ 7 - 7
cmd/smd/main.go

@@ -26,17 +26,17 @@ func main() {
 
 	g := &gonf.Config{}
 	g.Target(smd)
-	g.Description("command line tool for generating deliverable static content")
-	g.Add("template", "path to the template file", "STATICMD_TEMPLATE", "--template", "-t:")
-	g.Add("input", "path to the markdown files", "STATICMD_INPUT", "--input", "-i:")
-	g.Add("output", "path to place generated content", "STATICMD_OUTPUT", "--output", "-o:")
-	g.Add("book", "combine all content into a single file", "STATICMD_BOOK", "--book", "-b")
-	g.Add("relative", "use relative paths instead of absolute paths", "STATICMD_RELATIVE", "--relative", "-r")
+	g.Description("command line tool for generating static html from markdown")
+	g.Add("web", "parse into individual files matching the original file name", "STATIC_WEB", "--web", "-w")
+	g.Add("template", "path to user-defined template file", "STATIC_TEMPLATE", "--template", "-t:")
+	g.Add("input", "path to the markdown files", "STATIC_INPUT", "--input", "-i:")
+	g.Add("output", "path to place generated content", "STATIC_OUTPUT", "--output", "-o:")
+	g.Add("version", "optional user-defined version", "STATIC_VERSION", "--version", "-v:")
 	g.Example("-t template.tmpl -i . -b")
 	g.Example("-t template.tmpl -i src/ -o out/ -r")
 	g.Load()
 
-	if err := smd.Generate(operate); err != nil {
+	if err := smd.Run(operate); err != nil {
 		exit(1)
 	}
 }

+ 9 - 44
cmd/smd/readme.md

@@ -1,61 +1,26 @@
 
-# smd
+# [smd](https://github.com/cdelorme/static/tree/master/cmd/smd)
 
 This is the cli implementation and interface to the [static](https://github.com/cdelorme/static) library for generating html from markdown.
 
 
 ## alternatives
 
-There are far better tools written in a variety of languages which offer more features and better support.  _However they may also impose a runtime, special configuration, or special syntax_:
+There are far better tools written in a variety of languages which offer more features and better support.  **If you are working on anything remotely complicated, or that you intend to run in a production environment, it is recommended that you use one of these:**
 
-- [node; harp.js](http://harpjs.com/).
-- [golang; hugo](http://gohugo.io/)
+- [hugo (golang)](http://gohugo.io/)
+- [harp.js (node)](http://harpjs.com/).
 
-So, while the purpose of this project was self-education, what it provides is a very compact tool with minimal third party dependencies and no special requirements for configuration or syntax, wrapped in under 700 lines of code (including tests and comments).
 
+## installation
 
-## design
+To install the `smd` cli utility:
 
-This project assumes the following behaviors:
-
-- it tries all files even if it fails to read one or more of them, but it will produce a valid exit code
-- it assumes the current working directory (eg. where it is run from) is the input path
-- it assumes `public/` for the output path
-- it assumes absolute paths by default
-- it assumes a page per file by default
-
-_Most of these default behaviors can be overridden with command line parameters._
-
-The only required parameter is the path to a template file.  _An [example](template.tmpl) has been included with the project._
-
-If run within a repository it will attempt to grab a short-hash for the version, otherwise it generates a unix timestamp.
-
-It assumes the index files are `index.html`.  _If no match is found then no table of contents is created and no references to that folder will be created at the parent either even if it contains other markdown files._
-
-Currently it attempts to generate multiple pages in parallel.
+	go get -u github.com/cdelorme/static/...
 
 
 ## usage
 
-Install the utility:
-
-    go get -u github.com/cdelorme/staticmd/...
-
-The utility has builtin help to assist with using it:
-
-	staticmd help
-
-_Logging is completely controlled by the `LOG_LEVEL` environment variable, which accepts standard syslog severities with a default of `error` (use `silent` to turn off output)._
-
-You can use it to generate a single-page document that can be printed as a PDF and distributed with ease:
-
-    staticmd -t template.tmpl -s -c src/
-
-_This will generate a single file inside `src/`._
-
-
-## testing
-
-This code has unit tests that can easily be executed:
+By default the system produces a single page output.
 
-	LOG_LEVEL=silent go test -v -race -cover
+For more details on using the utility, run `smd help` for details.

+ 21 - 65
readme.md

@@ -1,88 +1,41 @@
 
-# [static](https://github.com/cdelorme/static)
-
-This is a go library written to provide static generation of html from markdown with a template.
-
-The intended function is to make it easy to convert large folders of documentation in bulk to explorable web content or a single-page document for printing as a PDF and redistributing.
-
-_The original goal of the project was to learn more about the programming language and tooling._
-
-
-## design
-
-The design focuses on three key outcomes:
-
-- absolute paths for a website
-- relative paths for local content
-- single-file with a table of contents
-
-It depends on:
-
-- markdown
-- a template
+[![GoDoc](https://godoc.org/github.com/cdelorme/static?status.svg)](https://godoc.org/github.com/cdelorme/static)
 
-_An [example template](cmd/staticmd/template.tmpl) has been provided._
-
-It automates two convenience outputs:
-
-- automatically generated index navigation
-- asset versions for cache busting
-
-
-### template
-
-A user-defined template affords you flexibility and control.
+# [static](https://github.com/cdelorme/static)
 
-A limited subset of variables are provided for your use:
+An abstraction ontop of [blackfriday](https://godoc.org/github.com/russross/blackfriday) for the purpose of accepting a folder of files and generating html in lexical order with built-in templates.
 
-- Depth
-- Version
-- Nav
-- Content
+_The primary objective of this project was originally self-education._  The result is a sub-par utility with minimal features.  The only benefits it offers are a significantly smaller code base, and no meta-data dependencies.
 
-The `.Depth` property is used when generating paths to global resources such as javascript, style sheets, and images.
 
-The `.Version` property allows you to address cached resources such as javascript, style sheets, and resources javascript may ask for.  _It is highly efficient as the cache will immediately rebuild using the new version._
+## usage
 
-The `.Nav` is the table-of-contents produced in single-page or "book" mode, and is empty otherwise.
+To import the library:
 
-The `.Content` is the file contents converted to html, and will have a table of contents automatically prepended to any `index.html` file deeper than the root of the output folder.
+	import "github.com/cdelorme/static"
 
-_Any assets hosted on a CDN can be given full paths, and it is recommended to host binary resources (such as images) and any javascript and style sheets there as well._
 
+## notes
 
-## usage
+Relative path support has been removed because raw markdown is intended to be readable.
 
-To import the library:
+Automatic navigation has been removed from the web solution, since the requirements vary by website and are entirely different when generating a book.  _Use the template override feature to create your own._
 
-	import "github.com/cdelorme/staticmd"
+The code makes no assumptions about what index name is used, since that is entirely controlled by the web server.
 
-To install the cli utility:
+The library is not concurrently safe, because there are zero benefits to running it concurrently.  Everything is bottlenecked at the hard drive, and that cannot be addressed without proper buffered solutions to both markdown and template parsing.
 
-	go get -u github.com/cdelorme/staticmd/...
+It uses [go-bindata](https://github.com/jteeuwen/go-bindata) to embed default templates, which have been committed to the project since `go generate` is not possible to do from `go get`.
 
-_The ellipses will install all packages below the main path._
+No efforts have been made to optimize re-execution around existing files, _but it would be possible to compare the markdown file modified time against the modified time of existing html files to reduce overhead in the future._
 
+If two files with alternative markdown extensions but identical base names exist, the first match is the only one that will be parsed into an html file.
 
-## future
+The book mode provides automatically generated navigation using javascript.
 
-In the future I would like to address the following:
+Any absolute links in book mode will not function as desired.
 
-- move page generation into a separate function
-	- consider offloading logic into `page` struct to cleanly separate code
-	- separation grants support concurrent execution of multi-page
-- move create-dir-if-not-exists logic into a separate function and call that from page generation
-- remove `back-to-top` from code
-	- _the `back-to-top` feature can be generated on-load via javascript_
-- streamline logic surrounding how absolute and relative paths are handled
-- standardize optimal navigation logic
-	- fix title acquisition to check for `title: ` or first header
-	- each nav struct can have an embedded []nav
-		- function exposed for template access to render recursively
-	- _every page should use the same navigation output in the same way_
-- switch to bytes.Buffer and buffered write for creating output file(s)
-- embed default template using the go-bindata utility with a fallback for a supplied template
-- add simple queue with rwmutex to safely process multi-file pages concurrently
+All tests have been (re) written using a black-box approach, where only publicly exposed functions and properties are modified.
 
 
 # references
@@ -90,3 +43,6 @@ In the future I would like to address the following:
 - [blackfriday](https://godoc.org/github.com/russross/blackfriday)
 - [function call from template](http://stackoverflow.com/questions/10200178/call-a-method-from-a-go-template)
 - [buffer blackfriday output](http://grokbase.com/t/gg/golang-nuts/142spmv4fe/go-nuts-differences-between-os-io-ioutils-bufio-bytes-with-buffer-type-packages-for-file-reading)
+- [github markdown file extensions](https://github.com/github/markup/blob/b865add2e053f8cea3d7f4d9dcba001bdfd78994/lib/github/markups.rb#L1)
+- [javascript queryselector](http://caniuse.com/#feat=queryselector)
+- [chaining writers in go](https://medium.com/@skdomino/writing-on-the-train-chaining-io-writers-in-go-1b39e07f71c9)