Developer's Diary
Software development, with Terry Ebdon
Markdown, Hosting & Documentation

Table of Contents

Tuesday 27th June, 2017

Internal commands in markdown

I encountered a Doxygen issue, with \internal.

I had a section like this:

\internal
## Internal Stuff {#privateStuff}
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore.
\endinternal

The above markdown hides the Internal Stuff section heading, when INTERNAL_DOCS = NO, but not the section text. To render the section correctly I had to remove the anchor:

\internal
## Internal Stuff

To add the anchor back, with correct rendering, use the \anchor command.

\internal
\anchor privateStuff
## Internal Stuff

This is the second issue I've had with markdown style headers. The Doxygen headers work a lot better. I stick with the markdown ones as they preview better in Atom and it's unusual for me to need an anchor.

Escaping in Doxygen Code Blocks

Tip: Prefer the \code command to fenced code blocks, for plain text.

I often use code blocks to illustrate the operation of markdown fragments. This works fine with the \code command. It does not work with markdown code fencing. In a fenced code block, that's not for a parsed language, Doxygen will interpret commands that it sees, e.g. \internal. The normal work-around for similar problems is to add an extra \, e.g. \\internal. But that renders as \\internal, which sounds like a bug. Switching to @, instead of \, has the same problem. The fix is to use \code ... \endcode, instead of fencing.

Hosting

These are some things I’d like to see:

  • Sub-domains – I can live without them, but they are very convenient for testing stuff.
  • SSL certs sites, at reasonable cost. The providers I looked at wanted $60 to $90 per domain!
  • SSL support for sub-domains, i.e. wildcard certificates, at reasonable prices.
  • Multiple e-mail accounts. It now seems common to limit you to five email addresses.
  • Server-side anti-virus / anti-spam. This is often an add-on, or just not provided.
  • Programmable web server (Servlet container, ASP.net or similar.)

I’ve been working around server-side restrictions by using “static generation” of web sites. I’m currently using Doxygen. But there are times when server-side processing comes in handy. e.g. Doxygen can run a client-side search or a server-side one.

One of the alternatives I looked at was Google. Not my preferred choice, but it’s usable and cost effective. It is, or at least was, free. You link your domain to your google account and create web sites with Google Sites or Blogger. Your domain email accounts then become Google accounts. I was tempted to hook a “spare” domain up to try this. Both Sites and Blogger allow public and private web sites, so they’re easy to test without using a domain. Microsoft Word and OneNote can both upload pages to Blogger, so that’s one way of creating stuff offline. I do like to test things thoroughly, on a local machine, before uploading.

Source Code documentation

Doxygen has a built-in source code browser. It can also use the HTML generated by htags.

WebDoxy – Creating Daily Summaries

I add a summary of each day's work to the corresponding entry on the month page. This is drudge work, so... let's start automating it.

A first attempt, in awk:

/^## / {
sub("## ", "")
print
}

This prints all second level headings from the input file, with the ## prefix removed.

Improved Doxygen Look and Feel

Increasing the Font Size

body, table, div, p, dl {
font-family: Lucida Grande, Verdana, Geneva, Arial, sans-serif;
font-size: medium;
}

Now the code block font looks too small, so:

/* The code block font will match the body text size.
*/
div.line {
font-size: medium;
}

In-line code fragments, enclosed in back-ticks, was too small and didn't stand out. So I changed its colour, and bumped the size up to match the body text:

/* Ensure <CODE> and <TT> text is as large as <BODY> text.
Use a nicer font. Make it green, to stand out.
*/
code, tt {
font-family: Consolas, Courier, monospace;
color: green;
}
/* Required as <PRE> makes the text look smaller due to different font */
pre {
font-size: 105%;
}

Converting "Go to Top" links to buttons

I added class=btn to the template and all existing diary pages. This was styled to a button with the following CSS:

a.btn {
background-color: #008cda;
border-radius: 7px;
color: #fff;
padding: 8px 20px;
text-decoration: none;
}
a.btn:visited {
color: #fff;
}
a.btn:hover {
background-color: #000;
}

Interesting web pages

Doxygen Customisation

Hosting

all-inkl.com

Installable Software

Source Code documentation

Science Open, ORCID and Authority Control

Top of Page Recent Posts The Archives © 2017 Terry Ebdon.

Find me coding on GitHub, networking on LinkedIn, answering questions on Stack Exchange and hanging out on twitter.