Error in documentation for HTML Import into a User Tool

[jlm]

I had some trouble today getting Accordance to recognize an HTML file as UTF-8, even though I'd copied the required tag from the documentation and pasted it into my file. It turns out there's an error in the tag in the documentation. When I corrected the error in my file, the file was recognized as UTF-8.

 

According to the documentation for Accordance 13 on macOS, the tag should be

<meta http-equiv="Content-Type" content="text/html; charset-UTF-8">

The error is that "charset-UTF-8" should be "charset=UTF-8". It won't work if there is a hyphen in place of the equals sign.

[jlm]

While I'm reporting, there's another error on the same page: according to the table,<em> produces bold in the User Tool. It actually produces italic, as one would expect.

[jlm]

As mentioned in another topic, support for <a href="accord://…"> is undocumented. Please add it to the table while you are making corrections.

[Mark Allison]

Thanks for the heads-up. I'll fix the help documentation asap.

[jlm]

Today I was looking for another piece of information, and I see that the above errors have not yet been fixed.

 

It seems there's another error: the documentation says <size 18> will make 18pt text. I want something in smaller text than the 12 point default, so I tried <size 10>Is 11:1</size>, but this had no effect. Since I don't think <size> was ever a standard HTML tag, I also tried <font size="10">Is 11:1</font> and <font size="-1">Is 11:1</font>, but neither of these worked either. FIrefox understands them (giving me enormous text for the first, and smaller text for the second), but Accordance does not.

 

Does anyone know the correct syntax to tell Accordance that text in HTML should be smaller than the default?

[jlm]

The Accordance 14 help hasn't fixed either of these issues. Now that tools are Unicode, the tag to specify the encoding is less important, but if it's in the help, it should be correct.

[Dr. Nathan Parker]

Thanks! I’ll report this.

[Accordance Enthusiast]

Hi @jlm,

 

Could you please tell me what program you are using to create these HTML files?
 

I would be very interested to know which works best. 

Edited January 31, 2023 by Anonymous

[Accordance Enthusiast]

I would also be very interested in some documentation which explains the basics of HTML specifically for Accordance modules. 

 

Any advice will be greatly appreciated.

[Dr. Nathan Parker]

Has anyone tried BBEdit for creating the HTML files? I’ve been playing with it (but not for Accordance modules). Looks like a solid HTML editor.

[jlm]

On 1/30/2023 at 7:40 PM, Anonymous said:

Hi @jlm,

 

Could you please tell me what program you are using to create these HTML files?
 

I would be very interested to know which works best. 

I work in Markdown, and use pandoc to convert it to HTML. You can try pandoc online here. Markdown is simpler to learn than HTML, more concise, and makes it easy to produce well-structured HTML. There is a large market for Markdown editors: any plain-text editor is sufficient, but there are various options that make the text look more like the formatted result when you're editing. On iOS, I've used Editorial and now Taio, which also runs on macOS. I'm keeping my notes in Obsidian, which is free and hides Markdown syntax on lines you're not editing. I've used Bear (iOS and macOS). For more complex projects, I use Visual Studio Code, which lets me track changes with Git, but that's more of a programmer thing.

 

PanWriter, Zettlr, and Quarto are Markdown editors that integrate with pandoc. I don't use any of them, so I can't make a recommendation. I just run pandoc on the command line (macOS). Visual Studio Code also has various extensions in its marketplace that integrate with pandoc, but I don't currently use any of them.

 

Note that there are various flavors of Markdown. Pandoc can ingest three of them (its own, GitHub flavored Markdown, and Commonmark), but some Markdown converters have additional extensions incompatible with pandoc (highlighting was an example until the pandoc 3.0), and pandoc has extensions that other Markdown converters don't support. For example, footnotes were not part of the original Markdown. Many converters do now support them, but pandoc also supports inline footnotes,^[I'm a footnote.] which most Markdown converters don't.

 

For me, the big advantage of pandoc over other programs that convert markdown, like multimarkdown, is that I can write filters in Lua to modify the document as it flows through the system. So if I have footnotes in the source document, and I'm outputting HTML for Accordance, which doesn't support footnotes or intra-document links, I can write a filter that places the footnotes by sticking a superscript number in the main text,¹ and adding the footnote text after the paragraph, in smaller type if I ever learn what syntax Accordance wants for that (the one in the manual doesn't work, as noted above).

 

1. Like this.

 

Markdown also has the flaw that there is no such thing as a syntax error. Whatever input you give it, you'll get some output, which may not be what you intended. So If you meant to make a word bold (like **this**), but you failed to type two asterisks after the word (like **this*), you might get output like *this instead of this. Of course, HTML doesn't accept tags with typos either.

 

[Accordance Enthusiast]

Thank you very much @jlm!

 

I'll have a look and try the options when I get some time.

 

It would be really great if we could make structured user tools for lexicons etc.

[jlm]

The two problems in the help that I reported at the beginning of this thread still haven't been fixed, and it doesn't seem like it would take much time to fix them. I checked the help displayed in Accordance.

https://accordancefiles2.com/helpfiles/14-macOS/index.htm#t=mac_14%2Fcontent%2Ftopics%2F05_dd%2Fhtml_import.htm

[Dr. Nathan Parker]

@Dan Dennison Can you look into this one?

[simonau]

@Dr. Nathan Parker, to be a world-class level software, I highly recommend Accordance ship with an example html to illustrate all the supported HTML tags based on https://accordancefiles2.com/helpfiles/14-macOS/index.htm#t=mac_14%2Fcontent%2Ftopics%2F05_dd%2Fhtml_import.htm. 

 

In Accordance 14, user tools support varies types: Dictionary, Greek Lexicon, Hebrew Lexicon, Commentary and General. It is even much better to provide example html for each supported type.

 

First it avoid confusion in between end user and your technical support.  

Second it is easy for a beginner (especially not familiar to HTML tags) to start with. 

Third it is also easy for Accordance to verify if there is any regression in between new version and patch update. It should be part of the QA job when sign-off the release. Honestly it is a few minutes task but ensure Accordance delivery a reliable product.

[Dr. Nathan Parker]

Good suggestion. Let me ask someone.