When writing perlpod documentation that will be exported to HTML, can I embed the title of the resulting HTML file in the POD directives?
I want to be able to convert multiple POD text files to HTML with the pod2html command, and don't want to have to give the --title="My Title" parameter on the command-line.
For example, here is a text file with perlpod formatting:
=pod
=head1 This is a heading
This is some text. I'd like to set the title of this document in the resulting HTML file.
=cut
When I convert it to HTML, pod2html gives a warning about there being no title:
$ pod2html test.txt > test.html
/usr/bin/pod2html: no title for test.txt
In the resulting HTML file, the title is set to the filename (test.txt):
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>test.txt</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root#localhost" />
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li>This is a heading.</li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<hr />
<h1><a name="this_is_a_heading_">This is a heading.</a></h1>
<p>This is some text. I'd like to set the title of this document.</p>
</body>
</html>
I'd like to find a way to have the title given in the perpod document, perhaps with a directive like this:
=title This is my custom title
In the Perl documentation, I see that the document titles are set nicely. Is this all done without having the document title in the pod document itself?
There is nothing in the Pod documentation that controls the title of the document. This up to the program that converts the Pod documentation to the format you want. Most of the pod2doc programs that you use to generate the documentation will have a module like Pod::Text or Pod::Html. These do most of the grunt work in converting.
pod2html takes a --title parameter. However, what you want is for pod2html to do it without you having to specify it. What you can do is roll your own version of pod2html. Let's look at pod2html script itself, and maybe you can figure out what you can do to get what you want.
Removing all the POD document, I see::
use Pod::Html
pod2html #ARGV
That's the entire program.
It looks like you could make a pod2steve program to do what you want. You want to take the last parameter (which I assume is what you want the title to be), and simply pass it through the pod2html subroutine. Your pod2steve would look something like this:
use strict;
use warnings;
use Pod::Html
my $program_name = $ARGV[$#ARGV];
pod2html --title=$program_name #ARGV
That should work.
No.
POD exists mainly¹ to write Perl module documentation², and therefore doesn't have many fancy features. Also, the primary output medium for POD is the terminal, where no such thing as a title exists conceptially³. It is, after all, just Plain and Old documentation.
1. Suprisingly many Perl books are written in POD.
2. The location of the POD document coincides with the thing discussed in the text.
3. The ps name / $0 variable comes close, but is useless here.
This is also a technical problem: pod2html uses Pod::Html, which parses the command line, and wraps itself around Pod::Simple::XHTML or something, without doing, or interfering with, the actual parsing. However, it already supplies a header and a footer, which sensibly overrides any default headers that might be emitted.
There are two interesting options how your problem can be solved:
You write a postprocessor that puts the value of the first h1 into the title. This should be <10 lines in a parser with XPath-support. Then you write a little script that ties these together, and can be invoked instead of pod2html.
You take the existing wealth of POD parsers (and source code), and whip up your own HTML from POD generator. If all you are actually doing is a small fork, you could try to offer the modification to the original module.
Related
I have tried numerous HTML preambles such as the following minimal example:
#+TITLE: Some math stuff
#+BEGIN_HTML
<script type="text/javascript"
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
#+END_HTML
=(solve a b)= should return $X$, from $AX=B$
The inline math works on my desktop if I export to HTML and view in my browser, but does not seem to be rendered in Github where the dollar signs are just echoed in the output.
Any idea on how to get Github to render inline math? Please note the answer to this question on how to do the same with README.md doesn't help as markdown is dissimilar to the much more featureful org mode.
EDIT: I have now learned how Github processes the .org file using github/markup which in turn uses org-ruby to parse the file. It appears that code blocks with #+BeginSrc etc are parsed very well but not the preamble lines or the inline math---though I have not really confirmed this yet.
#david This is the partial but hopefully relevant source from my webpage:
README.org
<article class="markdown-body entry-content" itemprop="mainContentOfPage"><h1><a id="user-content-some-math-stuff" class="anchor" href="#some-math-stuff" aria-hidden="true"><span class="octicon octicon-link"></span></a>Some math stuff</h1>
<p><code>(solve a b)</code> should return $X$, from $AX=B$</p>
</article>
</div>
Edit 2:
Signal for #VonC in the comments: GitHub supports Latex/MathJax since May 2022
https://github.com/github/markup/issues/274 seems to indicate that it's not currently possible. The issue was closed with no resolution.
I am automating documentation generation using Doxygen. How can I specify a favicon (URL icon) for the output?
In doxygen one has the possibility to define his own HTML header file, best based on the default HTML header file.
To obtain the default HTML header file, syntax:
doxygen -w html headerFile footerFile styleSheetFile [configFile]
in the headerFile insert in the head part a line like:
<link rel="shortcut icon" href="$relpath^my_icon.ico" type="image/x-icon" />
Note: that the $relpath^ part is necessary especially in case of CREATE_SUBDIRS is set.
Furthermore in the configuration file (Doxyfile) you have to set:
HTML_HEADER = headerFile
HTML_EXTRA_FILES += my_icon.ico
Of course the standard restrictions regarding favicons still apply (regarding support by browsers etc.).
I am using Emacs to write XHTML pages in a JSF project and the amount of boilerplate code that has to go at the header of each XHTML file is hard-to-type, ugly and error-prone. E.g:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:ui="http://java.sun.com/jsf/facelets">
What would be the "emacs way" of dealing with this? I 've read about the nXhtml mode but haven't tried it and don't know if it auto-completes boilerplate like the above or just offers more rudimentary XML checking / completion syntax. At any rate I would like to evaluate more lightweight alternatives first.
search for "template emacs". https://www.google.com/search?q=template+engine+emacs
here's a good survey: http://www.emacswiki.org/emacs/CategoryTemplates .
I use defaultcontent.el, which is one of the options listed on that page. Defaultcontent.el fills new files with a template depending on a pattern match on the filename. All .html files can get a particular template. You can do more advanced mapping of templates to files; defaultcontent.el uses an alist and you can specify any regex for the filename you like.
The template that gets placed into the new file can expand various things dynamically, including the filename, basefilename, date/time, environment variables. In more advanced scenarios the template can run elisp code that you provide.
It's a good companion to yasnippet, which I use for optional pieces of code within a file. For example, my base .htm template (inserted by defaultcontent.el) doesn't include a script reference for jquery. But I have a yasnippet for jquery , so that when I type (jquery[TAB]), I get the full expansion of
<script type='text/javascript'
src='https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.js'>
</script>
defaultcontent.el uses find-file-hooks and inserts template contents only when a file is initially created.
I use it for virtually all file formats.
I have a HTML file which gets generated by some tool. However, I need to use Perl to inset a newline after each line.
In a browser, if I was to view the source of this file, it would look something like this:
<body>
This is line number one
This is another line
This is also
Another line
</body>
Obviously this is just a snippet of the file. However, I think I would need to open this file and insert at the end of each line in order to format it, so that when viewed in a browser, it looks "nice".
Is this the most sensible / efficient method to employ?
Thank you.
If you want the file to appear on the browser in a way that more closely matches what you see when you open it with a text editor, there are several ways.
Perhaps the easiest is to encase the text in a <pre> block, this way the format is kept as-is.
<pre>
Hello,
this is
a test
</pre>
If you absolutely positively want to add a line break that will "work" with the browser, and you must use Perl, you might try something like this:
perl -n -e "print if s/\n/<br>\n/" < source.html > destination.html
This is pretty awful perl but it works.
You can achieve a similar result with sed:
sed -e "s/$/<br>/" < source.html > destination.html
I have a perl CGI script that needs to send back some HTML
print qq^Content-type: text/html\n\n
<HTML>
<HEAD>
<TITLE>some title</TITLE>
...
...
...
...
^:
Instead of seeing the rendered HTML in the browser, I see the entire HTML along with the tags and the 'content-type' line in plain text. Below is how things look in the browser -
Content-type: text/html
<HTML>
<HEAD>
<TITLE>some title</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#000000" VLINK="#000000" ALINK="#000000" BACKGROUND="" onLoad=document.forms[0].elements[0].focus();>
Seems like HTTP-header is sent before the output. Do you have any print statements (possibly in some function) before this code?
Also, try enabing warnings and strictures (if you have them off).
Also, as CGI scripts can be called without a web server, just call the script manually (with the right parameters / environment variables if they matter to the script and look at the output. As indicated by eugene y, the request headers must be the first output from the CGI script for them to be picked up by the server.
It sounds as if your server hasn't been configured to recognize certain file types as cgi executables. Assuming you are using Apache, adding this line to your httpd.conf will do the trick, although there are many other ways of configuring this to achieve the same effect:
AddHandler cgi-script .cgi .pl
You may also have to add ExecCGI to an options list for your domain. See Apache Tutorial: Dynamic Content with CGI for more information.
print "Content-type: text/html\n\n";
This tells the browser that the document coming after the two newlines is going to be HTML. You must send a header so the browser knows what type of document is coming next, and you must include a blank line between the header and the actual document.
So you need a blank line after "Content-type: text/html\n\n"