Tell me more ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.
up vote 2 down vote favorite

When documenting software I traditionally write a plain text file (like a README.txt) which works well, but unfortunately cannot contain images like HTML can. Unfortunately images must be stored as separate files with a normal HTML document (using <a href=".../foo.png">) which give unnecessary clutter.

The "Save a single web-page" in Internet Explorer use MIME HTML (MHTML) to save all resources within a single file. The requirement of having to use a browser to read it, is not a impediment these days. Apparently Opera and Word support editing these documents directly.

We use git for our source code, hence the differences as seen by git between two edits of the same documents should not be large to avoid unnecessary disk usage and unusable diff's when looking at the document outside the MTHML editor.

What is the best mainstream HTML editor for producing git-friendly MHTML files?

share|improve this question
3  
I for one, would prefer the images file to be external. Firstly, that would allow me to use my preferred text editor (VIM) on the files rather then fighting with an editor. Secondly, I often have external processes generate images. For example, I might have a class diagram generated by parsing the code. It easy to have a script update the images when they are external but very difficult if the images are internal. – Winston Ewert Dec 1 '11 at 14:49
4  
Don't do that. There's no reason to avoid external files. Clutter can be reduced by folders. Not using external files will complicate matters unnecessarily. – alex Dec 1 '11 at 18:13
Looks like no one has a real answer! – Dipan Mehta Mar 2 '12 at 16:54
@WinstonEwert do you have any input relevant to what I actually ask? – user1249 Mar 2 '12 at 17:02
@ThorbjørnRavnAndersen, if I had something that actually answered your question I would have posted it as an answer. I think the best solution is not to embed the images. Nevertheless, if I knew of a tool that would help I would tell you. But I don't. – Winston Ewert Mar 2 '12 at 17:12
show 1 more comment

5 Answers

up vote 4 down vote

I'd store images and text separately in source control; this way, even though your images are binary blobs (and thus not handled efficiently), you won't have a lot of small changes on binary files, provided you don't change the images themselves much.

Choose a documentation source format that fits your needs - HTML, Markdown, DocBook, LaTeX, etc. - and store only the sources (and the images you need to include) in source control. Then, just like with the code itself, you set up a build system, which allows anyone to build documentation in a consumable format (probably several of them, e.g. multi-file HTML, MHTML, PDF) from the sources.

share|improve this answer
Thanks for your suggestion. Would you happen to also have an answer to "What is the best mainstream HTML editor for producing git-friendly MHTML files?"? – user1249 Dec 1 '11 at 15:33
-1 for not answering the question. I wouldn't do it either, but that doesn't answer the question. – Winston Ewert Dec 1 '11 at 15:40
@ThorbjørnRavnAndersen: Unfortunately I am not aware of any usable editor that produces MHTML directly, let alone one that produces version control friendly MHTML. Hence my suggestion to generate (M)HTML from a version control friendly source format. – tdammers Dec 3 '11 at 10:18
up vote 4 down vote

You seem to be assuming that MHTML is the only way of embedding images into HTML. On the basis that that is an assumption rather than MHTML being an absolute requirement, I'd suggest using HTML and data URIs. That allows you to edit the text and get diffs using a standard text editor; if you're going to be editing the images a lot you'll probably want a text editor which supports base-64 en/decoding. Notepad++ has a standard plugin to do this, and I'm sure other editors targeted at programmers will too.

I should note that I've never used this approach for documentation, but I have used it for app_offline.htm pages.

share|improve this answer
If you have seen any other format with reasonable editors (i.e. not seeing raw image data) I'd like to hear about it. – user1249 Dec 1 '11 at 16:21
up vote 1 down vote

If, for some reason, you absolutely don't want external images, you could embed images in HTML as base64 (here is an online converter).

But I would personally rather have files as HTML (or better, Markdown) with images separated, and export/print to PDF if/when a single file is requested, that is easier to maintain.

share|improve this answer
Thanks for your suggestion. Would you happen to also have an answer to "What is the best mainstream HTML editor for producing git-friendly MHTML files?"? – user1249 Dec 2 '11 at 7:02
up vote 1 down vote

Use RTF format. Unlike DOC/DOCX it's neither binary nor compressed, so it DIFFS quite nicely. Inserting images puts them at the end of the file and reference inside, so it's as source control friendly as possible.

share|improve this answer
Would you happen to know a good editor which produce diff-friendly RTF-files? – user1249 Mar 2 '12 at 17:04
up vote 0 down vote

Why not try the approach with Markdown - that way, you can have HTML with images, and the "original" will still be in plain textual format, easy for diff.

share|improve this answer
1  
Is this in a single file as with MTHML or are the images external? – user1249 Dec 1 '11 at 14:07
1  
@ThorbjørnRavnAndersen, no Markdown can basically be seen as a simplified HTML syntax in this context – Winston Ewert Dec 1 '11 at 14:47
2  
@ThorbjørnRavnAndersen - Markdown files are plain text files, with the links to images being absolute or relative paths to the files. Images are separate than markdown (or html) files. The advantage of markdown is that it's plain text, no tags, and therefore can be easily diffed, or just printed out as they are - they're quite readable. Also, their popularity is growing quite fast the last few years. – ldigas Dec 1 '11 at 15:09
@Idigas, even though Markdown is nice, I still want my images embedded so I only have a single document. – user1249 Dec 1 '11 at 15:32
@ThorbjørnRavnAndersen - (Ldigas) Good luck then! I don't know of any format that embeeds images, and still makes it easy to let's say, do a diff. May I ask, what is the reason for such a decision? You're not only making it hard to compare different revisions, you're also making it hard to vcs it (version control is really ment for files that you can compare)), so you must have some strong reason for doing so. – ldigas Dec 1 '11 at 15:47
show 2 more comments

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.