I saw this related question about publishing toolchain but I know many people did lot of work to produce publishing toolchains recently.
One great example I found is this project from akosma.
Avdi Grimm shared his work with org-mode in this project
I know there are (should be) many others.
What I'm looking for, is a publishing toolchain with
asciidoc / markdown / textile / org-mode or latex input. I don't want xml input
pdf AND html output, epub output is not a requirement for me.
What I can
author templates in latex / html / css / js. again, no xml.
read and write ruby and shell scripts
Take a look at asciidoc, this is what O'Reilly has started using and it is a refreshing break from DocBook. I use asciidoc, the tools and support leaves a little to be desired, but there are people working to create better alternatives (that don't involve Python and the existing Docbook pipeline).
Check out this: https://github.com/runemadsen/asciidoc
EDIT 1/6/13: You also really need to check out AsciiDoctor. Dan Allen from RedHat has been spending a lot of time on this particular package and Ryan Waldron. I expect great things from AsciiDoctor as it is starting to emerge as a foundation for a bunch of important AsciiDoc documentation efforts.
Related
I need to write and build easy maintainable, goodlooking, esay to change documentation in pdf and html 5 format. The source format must be easy to edit. This maven plugin has to support my company organziation theam(fonts, colors, pictures etc.), TOC generation, separation of chapters in different files, integration of images files, easy way to put code snipets in the documentation. I have Maven build and I was wondering what is the current best descision to do that?
I was investigate two options:
Doxia - using md(markdown) as input format. There is WSWG md free
editor, support a lot of the aforemention stuffs, etc. Need external repo for its artifacts.
Asciidoctor - use asdcii doc as input format. Support templating using fragments etc.
What are the advantages and disadvantaes of using this plugins?
Are there any other good solutions?
From my attempts to build the documentation first with Doxia and then with AsciiDoc I realised that Asciidoc is the better. It allows
Easy styling using yaml files. Default styling is also very good.
Asciidoc as a mark-up language is very good documented: Uder Guide AsciiDoc
Has good online editors and the language is more powerful than markdown for example, and easier to write in comparison to the xml format.
Good examples when using with Maven and ascii doc and easy to understand configurations.
I have a problem :0
At my place of work we have two wiki systems and I have been charged with finding a way of migrating from a MediaWiki to a redmine wiki -- only problem is they use different markup languages (WikiText vs Textile) and a possible solution (Pandoc) only goes the other way :0 Any suggestions on how to do this would be greatly appreciated!!!
The MediaWiki to Redmine Migration Tool (MRMT) has just been released.
It migrates the whole history with the correct user assigned to each revision.
Besides a basic Pandoc translation it also adds some helpful replacements that will very likely be necessary in any migration of that kind.
The development version of pandoc now has a mediawiki reader. It doesn't support all of mediawiki syntax (e.g. templates), and it is not very well tested, but you could try it out.
You would need to install the development version of pandoc from source to do this. Install the Haskell Platform, then follow the instructions here.
(These instructions assume a *nix build environment.)
You will probably want to use some scripting to adjust the result, e.g. making links with title "wikilink" into proper redmine wikilinks. It is easiest to do this at the level of the pandoc AST, rather than in the textile result. The document on Scripting with pandoc on the pandoc website may be of help here.
Another approach is to scrape the HTML your redmine wiki produces, and use pandoc to convert that to textile. This approach typically requires a lot of preprocessing and postprocessing, though.
You could also try using one of the various alternative mediawiki parsers, producing HTML or DocBook and converting that to textile using pandoc.
There are many libraries for transforming markups like reStructuredText and markdown to HTML. I have some users who are familiar with the markup used in Atlassian's Confluence wiki product, which is unfortunately proprietary -- is there any open source compiler for the confluence wiki markup format, or possibly something that would transform it to an intermediate format?
I think Confluence uses the Textile markup format. I have used over the last few years a rails application that used the gem RedCloth to do the transformation, and I could switch between the 2 formats. I never checked if it is complete interchangeable, however.
You could check for yourself if it is sufficient at Try RedCloth.
I've been searching google for a while to determine the most coder-friendly example boxes.
I'm wanting to share varying forms of ECMA script (JS for example) etc that provides the user with color coding and a simple way of copying the code. I know there are several out there, but I wanted to get some opinions from SOF since you guys probably have good experience with code.
so- What's the code-sharing tool you [would] use?
the solution
I ended up using Gist for complete snippets and am using Syntax Highlighter for *incomplete * code samples. There's a Drupal plugin for the Syntax Highlighter, but I dare say it's more of a pain to figure out the plugin than it is to just do things the old fashioned way (old fashioned being like 5 years ago..)
I use http://jsfiddle.net/
Color coding — check
HTML, CSS, JS — check
Live demo — check
gist has syntax highlighting and users can download the files separately, as a zip archive or using git. You can embed the files easily on other sites.
Additionally, the site tracks changes and other users can add comments or fork a gist to change it themselves.
Anyone know of a wiki or wiki plugin that generates a PDF file or CHM file that spans the entire wiki?
I would like to have control of the table of contents.
I would like the internal and external links to work.
Ideally allow for tweaking the output template, but that is not a deal-breaker.
I want to generate content using WIKI syntax and mindset (lots of cross-links etc), but ship the content in PDF, CHM or an embedded application form. Something friendlier than installing the wiki software on the enduser machine...
XWiki does this out of the box.
The MediaWiki PDF Export extension allows you to select a group of PDF pages. I've not installed it yet, so unsure if it's easy to use that feature to select all the pages.
Confluence lets you choose pages when you export to PDF a space
But you can't customise a lot the PDF
You can customise it slightly through a theme (based on velocity)
Sphinx (https://www.sphinx-doc.org) is a fairly nice tool for generating HTML (or CHM) and PDF documentation, with wiki-like syntax. It is not a wiki; you can't edit through the web and generating HTML requires a build process. Still, it is pretty nice, with cross-references, fairly simple markup, and (in the HTML output) a search engine implemented in JavaScript with no server-side dependencies beyond static file hosting. Sphinx was developed for the new version of the Python documentation and is pretty themable; for example, the GeoServer project (which I work on, excuse the shameless plug) is using Sphinx with a custom theme for the new version of their user and developer manuals.
JIRA (http://www.atlassian.com/software/jira/default.jsp) is your geeky wet dream in terms of control; it exports to PDF (amongst other) and you can have complete control of pages, TOC and other aspects, although expect some complexity to set it up.
Microsoft has an HtmlHelp Authoring tool that can create chm files from html files.
If you need the help files both on the web and within deployed applications, generating the help from the same files used on the web could be a great solution. If the help site was created using asp.net (ie database driven) it might be worth using basic styles and creating a tool to generate html files by reading in the served out pages?
Have a look at: http://msdn.microsoft.com/en-us/library/ms524239(VS.85).aspx
I guess one could also additionally then create a PDF from the Html pages?