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.
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?
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 am creating a large LaTeX document, and my appendix has reproductions of several booklets that I have as PDFs. I am trying to create a section header and then include the pages at a slightly lower scale. For example:
\section{Booklet about Yada Yada Yada}
\includepdf[pages={-}, frame=true, scale=0.8]{booklet_yadayada.pdf}
However, pdfpagex does two annoying things. First, it devotes one output document page for included document page. I can live with that as I am using 80% scale. The main problem, however, is that the first page is also a new page, so I have a page with just a section title, and then a separate page with the booklet.
Is there some way to get pdfpages to be a little smarter here?
\includepdf uses \includegraphics internally, so something like
\section{Foo}
\fbox{\includegraphics[page=1,scale=0.8]{foo.pdf}}
would include the page without starting a new one, although it only does one page at a time.
For me the following worked just fine:
\includepdf[pages=1,pagecommand=\section{Section Heading}]{testpdf}
\includepdf[pages=2-,pagecommand={}]{testpdf}
I tried this solution too, but \includepdf keeps the advantage of outputting the file over the margin (the output is centered from the edges of the page).
So I openned pdfpages.sty, and I searched for \newpage command. I deleted the first occurance (line 326), just to try, and after saving then compiling again, there were no page break anymore.
Use the minipage environement :
\chapter*{Sujet du stage}
%\fbox{
\begin{minipage}{\textwidth}
\includepdf[scale=0.8]{../sujet-stage/main.pdf}
\end{minipage}
It doesn't add any extra page and it works with includepdf.
Thanks for all the answers - I couldn't for the life of me figure out what logic \includepdf uses to insert blank pages; the trick with including the first page via \includegraphics solved most (but not all) of those problems; so here are some notes:
First, out of curiosity, I have also tried to use only \includepdf, but split in two parts:
\includepdf[pages=1]{MYINCLDOC.pdf}
\includepdf[pages=2-last]{MYINCLDOC.pdf}
... unfortunately, this has the same problem as the question in OP.
Since #WASE's answer, there are now multiple \newpages in the source (pdfpages.sty). I tried reading the source, but I found it quite difficult; so I tried temporarily setting \newpage to \relax only for \includepdf - and that puts all pages in the document on top of each other; so probably not a good idea to get rid of \newpage blindly.
Just \includegraphics[page=1,scale=0.8]{foo.pdf} works - but (as #WASE also note) it is aligned at the top-left corner of the page body, which is to say inside the margins; for a full page we'd want the pdf inclusion overlaid over the whole page, margins included.
This page: graphics - How do I add an image in the upper, left-hand corner using TikZ and graphicx - TeX - LaTeX points to several possibilities for positioning on page over the margins; but for me, the best solution for a full page PDF inclusion is to use package tikz to center it to the page:
\begin{tikzpicture}[remember picture,overlay]
\node at (current page.center) {\includegraphics[page=1]{MYINCLDOC.pdf}};
\end{tikzpicture}
\includepdf[pages=2-last]{MYINCLDOC.pdf}
After this is done, as a bonus, I have also experienced:
Proper targets of PDF bookmarks (going to the right page when clicked)
If you use package pax, the data seems to be included also for the \includegraphics standalone first page, so no difference there
If you have a twoside document - pdfpages, with the above split of the first page in \includegraphics, will now (seemingly) correctly insert the equivalent of \cleardoublepages between pdfs that are included back to back (so I don't have to insert such a command manually).
Hope this helps someone,
Cheers!
I'm a little late, but the following solution worked for me:
\includepdf[pages={-},angle=90, scale=0.7]{lorem-ipsum.pdf}
All pages are imported, scaled and rotated by 90 degrees.
Works with Texmaker 5.0.4
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.