Hacker News Reader

Comment by srg0 | Hacker News Reader

"htmlq: like jq, but for HTML"

"jq is like sed for JSON data"

sed: "While in some ways similar to an editor which permits scripted edits (_such as ed_), sed works by making only one pass over the input(s)"

ed: "ed is a line-oriented text editor".

Software definition through a reference to another software is somewhat confusing. Potential users come from different backgrounds (I had no idea what is jq), and it is not clear what are the defining features of each project. Is jq line oriented? Is htmlq operating in a single pass?

View on HN

1st sentence - Explaining the tool for those the tool was made for without beating around the bush.

2nd sentence - Explaining the tool to folks in the general web domain what it can do for them.

3rd sentence - Explaining where to learn how to use the tool if you've stumbled across it but web is not your area of expertise.

All that info fits in nearly 25 words then it lists the options for the tool and jumps straight into multiple examples (with outputs!). If the only explanation had been "htmlq: like jq, but for HTML" I'd agree but having the comparison to explain what it does isn't a bad thing it's _only_ having the comparison that would be bad.

Personally I think this is a model example of a opening for a Github readme.

I disagree. The 2nd sentence contains, "extract bits content." What is that?

If you're going to write a minimal introduction, at least make sure it's not confusing.

I get the feeling the author felt compelled to write an introduction and did so with as little effort as possible.

I believe he tailored it to his target audience. If you find it confusing, you are likely not it.

As web developer for over a decade "bits content" doesn't mean anything to me. But I understand what the tool does from the rest of the description. Try running a google search for "bits content," [0] it's not a commonly used phrase in web development or anything. It's a poor choice of words.

0. https://www.google.com/search?hl=en&q=%22bits%20content%22

It's supposed to be "bits of content", it's not jargon. The author's just accidentally a word, we all do it.

It's more than fair to say in technical documentation you intend others to use having a grammatical error or missing word is confusing and a problem. It's the writing equivalent of having a bug in your code. And it's definitely not "writing to a target audience" as the parent comment suggested. We all make mistakes but don't try to call a mistake effective documentation.

Of course it is, but neither parent nor anyone else is saying anything close to the mistake being effective documentation. There's a single missing word which needs to be added in, but the overall text is clearly writing to a target audience. You are aware of this, and of how small the mistake is, and you understand what the sentence should read as, so I'm not sure what your point is?

My hunch is that this is a typo and it should read "extract bits OF content."

I agree and having a missing word in your text often leads to confusion :)

Honestly you could drop the "bits" which is a bit redundant and use the phrase "Uses CSS selectors to extract content from HTML files."

Exactly this! I’ll fix it after work.

Maybe have the line about "jq" be 2nd. Have the first line be a brief description of what it actually does.

"htmlq is like jq but for html" is a very specific 'dog whistle' for people who use jq. I agree that people who don't know what jq is will get no value and pay no attention. But for people who use jq, the claim is, like a dog whistle, clear, concise, and means exactly what it says. In two seconds, everyone using both jq and html will instantly know what is available and log it away.

So for general purposes, it's a terrible marketing pitch. And yet I think it's a very, very valuable demonstration of knowing some of their 'customers'.

this isn't what a dogwhistle is. it's just explanation by analogy to a model presumed to be shared by the intended audience. a dogwhistle offers a surface meaning to the uninitiated that's anodyne but communicates a hidden, coded message to those who possess some undisclosed, shared knowledge with the author. this kind of analogy entirely lacks the surface meaning and the message shared via jargon also communicates something about how you might learn enough to understand the analogy.

I can't speak for people who don't know jq, but knowing jq, this is a great tagline: it gives me an immediate understanding of what it does, how I could expect to use it and what value and ease of use I can expect.

I'll be trying it out next time I'm on a PC.

> I can't speak for people who don't know jq,

I can, and it's not illuminating at all.

I agree, however if you do know how to use jq than "like jq, but for html" is extremely effective. I use jq all the time and that title hooked me, I immediately wanted to try it.

But if you haven't used Jq that I can see how that title is less than helpful.

The first three are not proper definitions per-se but kind of an advertisement, trying to familiarize by self-comparison with a tried & true tool that has proven its worth.

You know Jimmy the famous mechanic? I'm Timmy, _his brother_ but an electrician.

IMO, at least `jq` has proven itself as the indispensable tool for json-data manipulation.

What's this thing called a "computer" that people keep going on about, anyway?

It's like a programmable loom, but for logical and mathematical operations.

You may be interested in the symbol grounding problem (https://en.wikipedia.org/wiki/Symbol_grounding_problem#Groun...). It's like the binding problem, but for symbols.

It's a person who does mathematic calculations all day. For example, creating range tables for artillery, calculating averages or totals of a large range of values, or solving complex integrals or differential equations, and so on. They're commonly used in industry or government, especially in astronomy, aerospace and civil engineering for both simulation and analysis. Perhaps the most well-known computers were the Harvard Computers, which operated in the late 19th and early 20th centuries.

As a job, computers were largely automated out of existence by solid-state transistor based automated computers and integrated circuit transistor automated computers in the 60s, 70s and 80s, which replaced the enormously expensive and often largely experimental electro-mechanical automated computers while radically reducing cost and improving performance both by several orders of magnitude.

Here - this explains it really succinctly:

https://www.youtube.com/watch?v=lE1bS-Mn2Mk

Sort of related: [Expecting Short Inferential Distances](https://www.readthesequences.com/Expecting-Short-Inferential...)

I mean...if you read the github readme it literally describes what it does in the next line: "Uses CSS selectors to extract bits content from HTML files".

> Software definition through a reference to another software is somewhat confusing.

Possibly, depending on background as you note, but not all promotion is intended at the same audience. When submitting to HN, "like jq, but for X" is short and conveys what it is to most the people that would care, I think. jq has been submitted and talked about here many times with lively discussion over the years.[1] At this point I think most those that are interested in what that is and what this is will understand fairly quickly from the title. Those that don't might be missed, or they might look it up like you, or they might see it through some other submission some other time with a different title which isn't based on a chain of references.

1: https://hn.algolia.com/?dateRange=all&page=0&prefix=false&qu...

jq isn't line-oriented, it's json-oriented. it's operaring on a stream of jsons from stdin, so its query is applied to each json in sequence.

I would expect that htmlq run the query a single time for a single html; just like jquery $('#something') or document.querySelector('#something')

Reply on news.ycombinator.com