News for hackers. Stuff that matters.
Re:Htmlq: like jq, but for html by srg0 on Tuesday September 07, 2021 @08:16AM (#28443751)
"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?

Re:Htmlq: like jq, but for html by zamadatix on Tuesday September 07, 2021 @08:47AM (#28444044)
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.

Re:Htmlq: like jq, but for html by zerocount on Tuesday September 07, 2021 @10:46AM (#28445517)
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.

Re:Htmlq: like jq, but for html by cyberge99 on Tuesday September 07, 2021 @11:05AM (#28445755)
I believe he tailored it to his target audience. If you find it confusing, you are likely not it.
Re:Htmlq: like jq, but for html by ritchiea on Tuesday September 07, 2021 @11:17AM (#28445901)
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

Re:Htmlq: like jq, but for html by chownie on Tuesday September 07, 2021 @11:25AM (#28445978)
It's supposed to be "bits of content", it's not jargon. The author's just accidentally a word, we all do it.
Re:Htmlq: like jq, but for html by ritchiea on Tuesday September 07, 2021 @11:29AM (#28446025)
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.
Re:Htmlq: like jq, but for html by RobertKerans on Tuesday September 07, 2021 @11:55AM (#28446272)
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?
Re:Htmlq: like jq, but for html by theIV on Tuesday September 07, 2021 @11:29AM (#28446021)
My hunch is that this is a typo and it should read "extract bits OF content."
Re:Htmlq: like jq, but for html by ritchiea on Tuesday September 07, 2021 @11:35AM (#28446084)
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."

Re:Htmlq: like jq, but for html by mgdm on Tuesday September 07, 2021 @12:12PM (#28446479)
Exactly this! I’ll fix it after work.
Re:Htmlq: like jq, but for html by rendall on Tuesday September 07, 2021 @01:50PM (#28447669)
Maybe have the line about "jq" be 2nd. Have the first line be a brief description of what it actually does.
Re:Htmlq: like jq, but for html by digitalsushi on Tuesday September 07, 2021 @09:40AM (#28444698)
"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'.

Re:Htmlq: like jq, but for html by acomar on Tuesday September 07, 2021 @10:50AM (#28445561)
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.
Re:Htmlq: like jq, but for html by philipswood on Tuesday September 07, 2021 @11:40AM (#28446143)
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.

Re:Htmlq: like jq, but for html by rendall on Tuesday September 07, 2021 @01:51PM (#28447689)
> I can't speak for people who don't know jq,

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

Re:Htmlq: like jq, but for html by throwaway2016a on Tuesday September 07, 2021 @09:01AM (#28444198)
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.

Re:Htmlq: like jq, but for html by ducktective on Tuesday September 07, 2021 @08:39AM (#28443962)
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.

Re:Htmlq: like jq, but for html by oauea on Tuesday September 07, 2021 @08:29AM (#28443859)
What's this thing called a "computer" that people keep going on about, anyway?
Re:Htmlq: like jq, but for html by da_chicken on Tuesday September 07, 2021 @10:10AM (#28445076)
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.

Re:Htmlq: like jq, but for html by theandrewbailey on Tuesday September 07, 2021 @08:52AM (#28444097)
It's like a programmable loom, but for logical and mathematical operations.
Re:Htmlq: like jq, but for html by samhw on Tuesday September 07, 2021 @10:01AM (#28444967)
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.
Re:Htmlq: like jq, but for html by sundarurfriend on Tuesday September 07, 2021 @10:57AM (#28445663)
Sort of related: [Expecting Short Inferential Distances](https://www.readthesequences.com/Expecting-Short-Inferential...)
Re:Htmlq: like jq, but for html by samstave on Tuesday September 07, 2021 @10:34AM (#28445368)
Here - this explains it really succinctly:

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

Re:Htmlq: like jq, but for html by corporealshift on Tuesday September 07, 2021 @09:06AM (#28444265)
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".
Re:Htmlq: like jq, but for html by kbenson on Tuesday September 07, 2021 @12:39PM (#28446836)
> 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...

Re:Htmlq: like jq, but for html by nextaccountic on Tuesday September 07, 2021 @11:19AM (#28445914)
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')