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?
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 am using Doxygen to create a product manual, and I ran into this issue.
Some links in the outputted PDF (created from LaTeX) are broken; they point to the first page of the document.
The accompanying HTML output does not suffer from this issue; links work just fine, as shown below:
The Doxygen code for this page:
/**
#mainpage [product] Developer's Guide
Blah blah blah.
This manual is divided into the following sections:
- #subpage intro
- #subpage [etc]
*/
Further notes:
I tried #ref instead of #subpage. No difference.
Some other references in the PDF are broken as well (automatic file references in some sections), but many work fine.
Here's the LaTeX intermediate for this page:
This manual is divided into the following section\-:
\begin{DoxyItemize}
\item \hyperlink{intro}{Product Introduction}
[etc]
Edit: Manual Solution Found
Open refman.tex from the LaTeX output directory
Change the entry \hypertarget{d1/dfb/intro}{} to \hypertarget{intro}{}
Repeat for other pages
Run the LaTeX to PDF tool
This is obviously not a viable solution for automated processes though, so this question is definitely still open.
As stated in the answer provided by #aaronncfca. The problem is caused by the not proper handling of paths in case CREATE_SUBDIRS is set to YES.
A, proposed,patch has been created for this problem and pushed (pull request 328) to github
Valid workaround found: Disable CREATE_SUBDIRS in the Doxygen configuration (Expert tab, Project topic in doxywizard).
The issue (as shown in the manual solution in my question) is that Doxygen puts the path in the hypertarget thing, where only the symbol is needed. By eliminating the path entirely, disabling sub-directories fixes the issue.
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!!!!
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.