I've written a load of technical documentation in Markdown. I chose to use this for versioning and so we can view in on GitHub.
We now need to share this with external users (who aren't as comfortable with Markdown), so I would like to convert it to PDF.
Gimli seems to be the best tool I have found for the conversion (it uses the same stylesheet as GitHub so it looks the same), however it doesn't convert the links as well. Is there anything that'll also do this?
I don't know with which type of links you have problems (inline links, reference links, HTML links, image links, automatic links...), but you can try to use Pandoc:
pandoc *.md -o result.pdf
This will convert all files with the *.md file extension to a single pdf.
I use named anchor tags in my markdown document. And I make links to these names. For example,
<a name="#1-overview"></a>
##1. Overview
......
Reference: [1. Overview](#1-overview)
Then I use Typora to open the markdown document and export it to PDF. The resulting PDF preserves these internal links properly.
NO!!! You really don't have to do this!!!
Simply " cat *.md > allpages.md " (you may want to organize the order manually or setup each file in a proper name to let cat work) then open the allpages.md then choose print / export in any markdown editor!!!!
You don't have to install ANYTHING!!!!
Related
Is there a method of linking to a heading in the same GFM README.md ("intra-readme" link) that works in both of the following situations?
(a) When formatted as HTML by GitHub
(b) When formatted as PDF by DITA-OT with Apache FOP
That is, I want something like (both of the following methods work in GitHub, but not in DITA-OT-built PDF):
[Link to custom anchor](#custom-anchor)
[Link to auto-generated anchor](#heading)
... intervening content ...
<a name="custom-anchor"></a>
## Heading
...
I think the answer is "No", but I thought I'd ask.
Some issues:
Auto-generated anchors, based on heading text, are incompatible: GitHub replaces spaces with hyphens (heading-text), whereas DITA-OT uses underscores (heading_text). It's occurred to me to write a DITA-OT XSLT override to change this behavior, but I'd prefer to avoid that.
DITA-OT supports Pandoc-style header attributes; GitHub doesn't.
DITA-OT Markdown processing generates a topic for each heading.
Background to this question
For now, I am deliberately and exclusively using README.md files to document a GitHub repo. I am not, for example, using GitHub Pages. Most directories in the repo contain a README.md file. For now, the readme content is enough.
Some users like docs in PDF. For those users, I have created a DITA map that refers to all of the README.md files, and I use the DITA Open Toolkit (DITA-OT) with Apache FOP to format that DITA map to PDF, resulting in a single PDF file that consolidates all of the content from the multiple readmes. I have my own reasons for using DITA-OT rather than, say, Pandoc. While I appreciate there are other ways to generate PDF from Markdown, I'm interested in DITA-OT-specific answers.
I can link from one readme to another ([Link text](subdir/README.md))—such links work in both GitHub-formatted HTML and DITA-OT-built PDF—but I can't figure out how to do "intra-README.md" links, hence this question.
I hate long comments in C source code, so where absolutely needed, I want to put single-line comments with a file:// URI pointing to the explanation (chapter or a page in the documentation). This already works with the PDF (source), but what I really need is this to work for Markdown documents.
From the link that I posted I know it's possible to create a URI that points to a PDF page e.g.:
http://www.example.com/myfile.pdf#page=4
or a PDF chapter:
http://www.example.com/myfile.pdf#glossary
Vim's g + x does not work with this, but there is a fix on the way (here):
Is there a similar way for URI to point to a Markdown chapter or Markdown page (I doubt the last one)?
If this is not possible... is there a Vim plugin that enables something like that?
I'm going from docbook to fo to pdf and I need to have text that goes to different parts of the document when clicked. I'm using the following format
<link linkend="M1350424Trace">
<emphasis role="bold">Link To Trace</emphasis>
</link>
Where M1350424Trace is the id of a paragraph. It works how I want it to work when I'm linking to something that comes later in the document but not when it's trying to link to something that comes earlier. Why is that?
Here's the .fo
<fo:basic-link internal-destination="M1350424Trace">
<fo:inline>
<fo:inline font-weight="bold">Link To Trace</fo:inline>
</fo:inline>
</fo:basic-link>
I've reproduced your case with the following input data:
Sample DocBook file with link and xref as a linkage mechanism
link and xref both and the target id are on different pages after rendering.
DocBook 5.1 as a source.
DocBook XSL 1.79.1 - as a stylesheets.
FOP 2.3 as a renderer.
The produced PDF file was tested with xpdf 3.04, Acrobat Reader 7.08 on Linux Debian 9.5
Works as should be: pressing the link moves to the page with a required element (para) with a required id number.
So you need to provide the exact file and exact configuration that raised this strange behavior. You can fill it with a dump data in case your document is under NDA or contains sensitive information, BUT it should be the same in matter of structure and elements within as an original one.
I'll try to reproduce your case.
Does the Sphinx documentation tool offer different PDF themes like it offers different HTML themes?
I Googled the issue but can't find an answer, which leads me to believe the answer is 'no'. Still, i thought i'd ask here.
Thanks.
Firstly, Sphinx doesn't generate PDF output by itself, though there are three general methods to get from Sphinx source files to PDF output:
Use the Latex builder, and then a separate tool like latex2pdf to generate the PDF output
Use the Sphinx plugin from the rst2pdf project
Use the rinoh Sphinx builder provided by rinohtype
That being said there is lots of potential for customizing the styling of your PDF output using either method.
When using the latex->pdf method, you can customize your latex output using a number of options in your sphinx config file. See here. This method is somewhat less convenient than the HTML themes that Sphinx uses for HTML generation, though (IMO).
When using rst2pdf you can define your own stylesheet, which is described in more detail in the manual (look under the "Styles" heading). rst2pdf includes a number of stylesheets, which can be combined for various results. And of course, you can also modify them or create your own (they're just JSON files). These stylesheets also support a kind of inheritance, so act more like the Sphinx HTML themes than the previous method.
rinohtype has extensive provisions for styling a document. See the Basic Document Styling and subsequent sections of the rinohtype manual.
There are no predefined themes for PDF output for Sphinx. But LaTex offers a rich set of options to style the document. My problem was to find the proper way to style the document with sphinx. Here the way, which worked for me:
First take a look into the conf.py. There you'll find an option latex_elements. With this option you can add your own LaTex commands to the output. For example:
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
'pointsize': '12pt',
'fontpkg': r"""
\PassOptionsToPackage{bookmarksnumbered}{hyperref}
""",
# Additional stuff for the LaTeX preamble.
'preamble': r"""
\usepackage{setspace}
""",
'footer': r"""
""",
'maketitle': r'''
\pagenumbering{arabic}
''',
}
There are a few points important to know.
Use r""" to avoid conflicts with python
Though preamble would be the right point to add \usepackage you can have conflicts with the Sphinx default settings. Look at fontpkg in the example. It is the first include in the .tex output document. If you have to set options for default packages, do it here.
maketitle let you define your own title page. See some latex documentation. I set \pagenumbering there to have the table of contents with arabic numbers, so the real content begins on page "1".
With the right knowledge of Latex commands you can get good theming with a few commands. A good source to find help is https://tex.stackexchange.com/ where most common problems have a solution. But finding the proper Latex commands is much more difficult than to choose a theme as done for HTML.
It might be helpful to take a look in the Tex-Output under ./_build. There you can see, how the latex_elements-options were included in the document.
I'm looking for site similar to http://www.manoli.net/csharpformat/ that allows one to put in c# code snippet and it formats the html to post into your blog with a CSS file.
I need one that actually does this for Objective-C.
You want the GeSHi (Generic Syntax Highlighter) library. It's is excellent, has dozens of languages (including Objective-C, with the ability to automatically linkify classes/protocols to the documentation), and support for many popular CMSs (Django, WordPress, Drupal, Joomla, Mambo, etc).
If you'd like to see it in action, you can check out nearly any wiki page on our local CocoaHeads website. For example: http://cocoaheads.byu.edu/wiki/different-nslog
Assuming you're on a Mac, copying code from Xcode will keep the syntax coloring. Any WYSIWYG blog editor should support that.
In case your blog software isn't WYSIWYG, you can paste into TextEdit and save as HTML. It outputs pretty crappy HTML considering it's just highlighted source code, but it's nonetheless compliant HTML.
Other than that, I don't know of an online service for that.
I use pygments (python) to generate syntax highlight for source code examples embedded in blog.
If your entry text is just the source code it will work the same for what you are after, I tested it to highlight Objective-C as well.
I actually use markdown syntax to type plain text blog post in a file and I copy plain text code examples. Then I run the file via markdown processor, which includes pygments for highlight and store it into a file.
It's as simple as:
include markdown
html = markdown.markdown(text,['codehilite'])
See simple script at the link which just takes file name of your plain text file and creates html file.
Then I can copy/paste the code.
You have to include link or copy the css as well to get the syntax highligh but it's easy.
I do this for blogger, see example how to use markdown with pygments to do syntax highlight.