foundweekends / pamflet

a publishing application for short texts

Pamflet is a publishing application for short texts, particularly user documentation of open-source software. It is designed to be easy to write and read on any platform.

See Pamflet's pamflet for the full story.

pamflet's Issues

Support fragment navigation in TOC by emitting `id` attributes for each href

This first came up on the SBT gitter channel. @eed3si9n mentioned that the HowTo section might be the right place to put some docs, and incidentally I noticed some bad UX if you just want to view all the HowTo articles - you have to scroll down for like 10 screen to get to them - as can be seen here:
http://www.scala-sbt.org/0.13/docs/Howto.html

Because the SBT whole TOC is huge, it would be nice to be able to fragment link to a specific place within the TOC. That would be enabled if pamflet converted & emitted each page.name into an id for each href, about here I think: https://github.com/n8han/pamflet/blob/29eb5483b5bdd56c8fb38e55b6c853c862439352/library/src/main/scala/printer.scala#L39

Improved print stylesheet

Make the print stylesheet really nice (then maybe we can get away without built-in PDF export for a while).

Publish to github pages

The pf tool should be able to automatically commit to a gh-pages branch for easy publishing through github pages.

support Scala 2.12

• tristanjuricek/knockoff#48

I haven't touched scala in a few years, I'm gonna try to figure out some kind of automated workflow. Hold tight.

downcasing page uris

I was surprised with http://unfiltered.databinder.net/Unfiltered.html was resolved but http://unfiltered.databinder.net/unfiltered.html wasn't. I think if you are hosting this behind apache or other http proxy you can probably handle this with a re-write rule but I wonder if it would make sense to downcase uris by default.

wdyt?

Index page

Lists all pages as well as their headings, with links that target the heading.

Support for github-style table markup

To go in the knockoff extension module.

Custom CSS not used when project base specified as input

Specifying full path to docs directory causes the css to be used. When the base path is supplied pf should either error out or work correctly.

per-page properties to override file name etc.

steps

1. write 00.markdown with some title.
2. add template.properties.
3. run pf.

problem

the generated page uses title as html file name. I would like a way to override that behavior somehow.

per-page properties

optionally properties can be added that applies only to the page:

---
out: index.html

---

title at the top should be a link to the index

...at least that what my intuition tells me. I can grab this. Shouldn't be too hard.

IE Support, more graceful degrading

Pamflets are illegible on IE 7 and use the mobile stylesheet is used on IE 8. If you force IE 8 to use the desktop stylesheet it looks broken, though it is legible.

The default desktop stylesheet should not be so brittle.

Sections

Need some kind of hierachy for the TOC, to group related pages together.

Ideally it's arbitrarily deep and defined by numbered directories.

tut integration

https://github.com/tpolecat/tut

"Version 0.6.0 Release Notes" link is to 0.5.0 release notes

The link "Version 0.6.0 Release Notes" at the main documentation page actually links to 0.5.0 release notes.

prominent github link

A "fork me on github" banner, or something, should be easy to add to pamflets.

In-page Navigation

Pull out all headings for the current page to show them as a section listing, similar to page contents in Wikipedia example.

I have some reservations about this pushing down the main content. One thing I'd like to try is to have it shown by request, as a pulldown from the fixed header. (Currently that header is not fixed in place for a good reason, but I've had in mind to build interactive features into it an this is a good candidate.)

It's possible there will be some confusion between this contents and the full-pamflet contents that appear at the bottom of each page. How can this be logically resolved? Would it make much more sense to have the current page's section content's be nested into the main contents? If so, then that has to go up top, and significantly push down the content. It can not be interactively displayed because the browser's "find in page" feature should always be able to find the names of other pages, IMO.

Optional inverted color scheme

Would be really handy for mobile

ToC on the left

I feel like for many of the Pamflet sites that I maintain, ToC displayed on the left would work better instead of the bottom of each page.

Error finding for scripts for n8han/pamflet

Just installed conscript with setup.sh, now i tried to install pamflet and i got this:

$ cs n8han/pamflet
Getting net.databinder conscript_2.9.1 0.3.4 ...
downloading http://scala-tools.org/repo-releases/net/databinder/conscript_2.9.1/0.3.4/conscript_2.9.1-0.3.4.jar ...
[SUCCESSFUL ] net.databinder#conscript_2.9.1;0.3.4!conscript_2.9.1.jar (3452ms)
downloading http://scala-tools.org/repo-releases/net/databinder/dispatch-http_2.9.1/0.8.5/dispatch-http_2.9.1-0.8.5.jar ...
[SUCCESSFUL ] net.databinder#dispatch-http_2.9.1;0.8.5!dispatch-http_2.9.1.jar (1785ms)
downloading http://scala-tools.org/repo-releases/net/databinder/dispatch-lift-json_2.9.1/0.8.5/dispatch-lift-json_2.9.1-0.8.5.jar ...
[SUCCESSFUL ] net.databinder#dispatch-lift-json_2.9.1;0.8.5!dispatch-lift-json_2.9.1.jar (1504ms)
downloading http://scala-tools.org/repo-releases/com/github/scopt/scopt_2.9.1/1.1.2/scopt_2.9.1-1.1.2.jar ...
[SUCCESSFUL ] com.github.scopt#scopt_2.9.1;1.1.2!scopt_2.9.1.jar (1662ms)
downloading http://scala-tools.org/repo-releases/org/scala-lang/scala-swing/2.9.1/scala-swing-2.9.1.jar ...
[SUCCESSFUL ] org.scala-lang#scala-swing;2.9.1!scala-swing.jar (4776ms)
downloading http://scala-tools.org/repo-releases/net/databinder/dispatch-core_2.9.1/0.8.5/dispatch-core_2.9.1-0.8.5.jar ...
[SUCCESSFUL ] net.databinder#dispatch-core_2.9.1;0.8.5!dispatch-core_2.9.1.jar (2152ms)
downloading http://scala-tools.org/repo-releases/net/databinder/dispatch-futures_2.9.1/0.8.5/dispatch-futures_2.9.1-0.8.5.jar ...
[SUCCESSFUL ] net.databinder#dispatch-futures_2.9.1;0.8.5!dispatch-futures_2.9.1.jar (1406ms)
downloading http://repo1.maven.org/maven2/org/apache/httpcomponents/httpclient/4.1/httpclient-4.1.jar ...
[SUCCESSFUL ] org.apache.httpcomponents#httpclient;4.1!httpclient.jar (19955ms)
downloading http://repo1.maven.org/maven2/org/apache/httpcomponents/httpcore/4.1/httpcore-4.1.jar ...
[SUCCESSFUL ] org.apache.httpcomponents#httpcore;4.1!httpcore.jar (14139ms)
downloading http://scala-tools.org/repo-releases/net/liftweb/lift-json_2.9.0-1/2.4-M3/lift-json_2.9.0-1-2.4-M3.jar ...
[SUCCESSFUL ] net.liftweb#lift-json_2.9.0-1;2.4-M3!lift-json_2.9.0-1.jar (3917ms)
downloading http://scala-tools.org/repo-releases/org/scala-lang/scalap/2.9.0-1/scalap-2.9.0-1.jar ...
[SUCCESSFUL ] org.scala-lang#scalap;2.9.0-1!scalap.jar (4403ms)
:: retrieving :: org.scala-tools.sbt#boot-app
confs: [default]
14 artifacts copied, 0 already retrieved (3242kB/46ms)
Error finding for scripts for n8han/pamflet

release 0.7.0 final

add support for UTF-8 encoding of docs

Currently, all files in the docs / SRC folder are read using the default encoding, e.g. ISO-8859-1 / Latin-1. I suggest to add an optional setting to the file template.properties allowing to specify a custom file encoding.

publish documents to new site

• http://www.foundweekends.org/pamflet ?
• gh-pages branch of https://github.com/foundweekends/pamflet ?
• any other ?

All Pages view

Generate one html that contains the full content in one page.

Search engine

Implemented in JS, with a generated token index in json. (Seriously!)

java.io.FileNotFoundException "docs/template.properties (No such file or directory)"

steps

1. make docs folder and write 00.markdown.
2. run pf.

problem

Previewing `docs`. Press CTRL+C to stop.
2012-01-30 10:02:03.246:WARN:oejs.ServletHandler:/xyz.html
java.io.FileNotFoundException: docs/template.properties (No such file or directory)
    at java.io.FileInputStream.open(Native Method)
    at java.io.FileInputStream.<init>(FileInputStream.java:120)
    at pamflet.StringTemplate.properties(template.scala:24)
    at pamflet.StringTemplate.get(template.scala:27)
    at pamflet.Printer.print(printer.scala:138)
    at pamflet.Printer$$anonfun$printNamed$1.apply(printer.scala:155)
    at pamflet.Printer$$anonfun$printNamed$1.apply(printer.scala:155)
    at scala.Option.map(Option.scala:133)
    at pamflet.Printer.printNamed(printer.scala:155)
    at pamflet.Preview$$anonfun$apply$1.apply(preview.scala:15)
    at pamflet.Preview$$anonfun$apply$1.apply(preview.scala:9)
    at scala.PartialFunction$$anon$3.apply(PartialFunction.scala:67)
    at scala.PartialFunction$$anon$3.apply(PartialFunction.scala:66)
    at unfiltered.response.Pass$PartialAttempt.attemptWithPass(pass.scala:67)
    at unfiltered.response.Pass$PassingAttempt$class.attempt(pass.scala:60)
    at unfiltered.response.Pass$PartialAttempt.attempt(pass.scala:62)
    at unfiltered.response.Pass$$anonfun$fold$1.apply(pass.scala:43)
    at unfiltered.response.Pass$FunctionAttempt.apply(pass.scala:72)
    at unfiltered.filter.Plan$class.doFilter(plans.scala:47)
    at unfiltered.filter.Planify.doFilter(plans.scala:53)
    at org.eclipse.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1330)
    at org.eclipse.jetty.servlet.ServletHandler.doHandle(ServletHandler.java:478)
    at org.eclipse.jetty.server.handler.ContextHandler.doHandle(ContextHandler.java:941)
    at org.eclipse.jetty.servlet.ServletHandler.doScope(ServletHandler.java:409)
    at org.eclipse.jetty.server.handler.ContextHandler.doScope(ContextHandler.java:875)
    at org.eclipse.jetty.server.handler.ScopedHandler.handle(ScopedHandler.java:117)
    at org.eclipse.jetty.server.handler.ContextHandlerCollection.handle(ContextHandlerCollection.java:250)
    at org.eclipse.jetty.server.handler.HandlerWrapper.handle(HandlerWrapper.java:110)
    at org.eclipse.jetty.server.Server.handle(Server.java:345)
    at org.eclipse.jetty.server.HttpConnection.handleRequest(HttpConnection.java:441)
    at org.eclipse.jetty.server.HttpConnection$RequestHandler.headerComplete(HttpConnection.java:919)
    at org.eclipse.jetty.http.HttpParser.parseNext(HttpParser.java:582)
    at org.eclipse.jetty.http.HttpParser.parseAvailable(HttpParser.java:218)
    at org.eclipse.jetty.server.BlockingHttpConnection.handle(BlockingHttpConnection.java:50)
    at org.eclipse.jetty.server.bio.SocketConnector$ConnectorEndPoint.run(SocketConnector.java:245)
    at org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:598)
    at org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:533)
    at java.lang.Thread.run(Thread.java:680)

expectations

it works without template.properties.

HTML-style commenting

steps

<!--

## some complex markdown
- list
- list

-->

problem

expectation

I would like the above to render to nothing.

Source code highlighitng

Source code should be highlighted, and we're probably going to find better highlighters in javascript than on the JVM.

Wants from the JS library:

• Broad language support
• Should blend in with the page, no boxes or backgrounds
• No frills line numbers or toolbars

Candidates:

• http://code.google.com/p/google-code-prettify/
• http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/scala.html

It will be up to pamflet to give writers a way to enable/disable highlighting, to specify the programming language, or if they do want line numbers, etc. This is normally done with style classes, and knockoff doesn't support any extended markdown to specify these, so pamflet has to either

• Tell people to use a pre tag -- does that make it harder to enter code?
• Implement one of the markdown extensions for classes--ha.
• Invent some other way to specify these options for source code that is just general enough to work.
• Fenced blocks already invented by github, suggested by philcali