search

ioccc-src / temp-test-ioccc

Temporary test IOCCC web site that will go away
Creative Commons Attribution Share Alike 4.0 International
33 stars 6 forks source link

Enhancement: improve markdown links to FAQ entries #2417

Open lcn2 opened 4 weeks ago

lcn2 commented 4 weeks ago

Is there an existing issue for this?

Describe the problem

In regards to markdown links to FAQ entries:

Relevant images, screenshots or other files

Consider these FAQ entry markdown links:

contact.md: * **Fix a winning IOCCC entry** - See [FAQ 5.2](faq.html#fix_an_entry)

index.md: See [FAQ 0.0: How may I submit to the IOCCC?](faq.html#submit) for more information.

thanks-for-help.md: See [FAQ 4.6  - Why was arg count and/or type changed in main() in some older entries?](faq.html#faq4_6) for more details.

status.md: are in the process of judging the [submissions](faq.html#faq2_0) they received while

news.md: See "[FAQ 6.12: What is Mastodon and why does IOCCC use it?](faq.html#try_mastodon)" for more

What you expect

Regarding markdown links to FAQ entries:

Environment

n/a

Relevant links

n/a

Anything else?

See also comment-2161538434, and comment-2161543051, and comment-216169570.

xexyl commented 3 weeks ago

Oh I like how the templates I added turned out!

Please assign this to me too and I'll look at it later - as you say, after #2006 is done.

I might add that unrelated I STILL have a problem with the IP changes. My registrar has problems with glue record set up and if you have IPv6 addresses you have to contact them. Well the old addresses, IPv6 and IPv4, for the slave DNS server that still exists (I was able to delete the ones that no longer exist) have the old IPs so I just sent them an email ... I decided to not bother with the new IPv6 address as that would mean I would have to email them again.

This way it is hoped that when I get the new IPs (hopefully in the not too distant future) I can fix it myself. I am also thinking about seeing if I can get DNSSEC working again. I must also now fix another problem (simple one at least that will take very little time: just updating one of the NS RRs in some of the zone files).

I am not sure what I can do here at the repo today but I hope to at least resume where I left off yesterday.

Anyway please do assign this task to me when you see this message: for I know you can't assign an issue to someone until they reply.

xexyl commented 3 weeks ago

One thing I noticed here though is it looks like the tickbox of 'I have searched for ..' makes it like a task list. Hmm ... or did I miss a list you added? I can believe that as I didn't look at it in full and I'm not completely awake either but if it did do that we might want to look at doing it differently, maybe? What do you think? It could just be a text box that they say 'yes' to or something so as to not confuse it as a task list?

lcn2 commented 3 weeks ago

One thing I noticed here though is it looks like the tickbox of 'I have searched for ..' makes it like a task list. Hmm ... or did I miss a list you added? I can believe that as I didn't look at it in full and I'm not completely awake either but if it did do that we might want to look at doing it differently, maybe? What do you think? It could just be a text box that they say 'yes' to or something so as to not confuse it as a task list?

That it is a checkbox ✅ isn't a problem. And it looks nice, don't you think?

Yes, the template looks good 👍

xexyl commented 3 weeks ago

One thing I noticed here though is it looks like the tickbox of 'I have searched for ..' makes it like a task list. Hmm ... or did I miss a list you added? I can believe that as I didn't look at it in full and I'm not completely awake either but if it did do that we might want to look at doing it differently, maybe? What do you think? It could just be a text box that they say 'yes' to or something so as to not confuse it as a task list?

That it is a checkbox ✅ isn't a problem. And it looks nice, don't you think?

Yes, the template looks good 👍

I think it looks nice but I also think it's unfortunate that it thinks that it's a task list.

But I agree that the tickbox is a good idea too. I just wish it didn't interpret it as a task list. That might be misleading.

Okay okay! The irony is of course this is for the IOCCC 😀 but still not everything needs to be obscure .. :-)

Thanks for assigning. I will look at it after the top priority issue is done. If however any part of that leads me to making slight fixes here then I will but I won't actually work on fixing the whole thing until after the other issue.

Though of course maybe when you are done with your other things that you have been forced to do you might also look into this.

Too bad this can't all be automated. Some of it could be but it's too convoluted to do it completely. At least once the tags are in the links can be updated easily. But of course the name for the links should be consistent and that can't be automated in every case for reasons I brought up.

lcn2 commented 3 weeks ago

We believe we have addressed all of the current questions that still need answering at this time. If we've missed something or something else needs to be clarified, please ask again.

xexyl commented 2 weeks ago

Something just occurred to me. Okay that's not strictly true: I have thought of it before but I think it'd be useful to do.

Since we're going to improve the links it might be a good time to try and do this as we will be changing the links anyway to not refer to the FAQ number. I believe we should reorganise the FAQ itself wrt the sections. In other words we should have more sections. Looking at the FAQ you see a number of questions about authors but it would be good I think to have a section on winning authors. This is all the more the case as I am going to be adding another FAQ about it: since you don't want to put URLs and other information on the index.html pages there should be an FAQ about how to find that information.

I am not saying that the only section to be added should be about authors but neither am I saying that there should be any others necessarily (though I think there should be). In particular the Miscellaneous questions should be broken up, I think.

Something that can be included in the author section should be the json files related to them but not strictly that. Since we'll be adding name tags this can work. I think it might be nice to do this before the merge too in which case it might be part of my work on the FAQ at the end of #2006.

Also I think it might be nice to separate the how to compile and run the entries and how to download them: not only the tarballs but individual files. it might also be nice (when the syntax highlighting feature is added which I know is not supposed to happen until after the merge) to have an FAQ about the syntax highlighting. But of course this can be added before but modified later: since GitHub does have syntax highlighting it can refer to that.

Just some examples that very easily could be and probably should be modified some (or a lot!).

lcn2 commented 2 weeks ago

Our suggestion is that the FAQ not be reorganized at this time: certainly not until this issue is resolved.

Later, if there is time after this issue is resolved and before code freeze (say because the screenshots for the submit server and registration are not ready) a FAQ reorganization can be done.

xexyl commented 2 weeks ago

Our suggestion is that the FAQ not be reorganized at this time: certainly not until this issue is resolved.

Later, if there is time after this issue is resolved and before code freeze (say because the screenshots for the submit server and registration are not ready) a FAQ reorganization can be done.

Sure. It can always come later .. or not.

lcn2 commented 1 week ago

We see the value in reorganizing the FAQ

Let's decide on how FAQs should be externally referenced, given the constraints in the top comment soon.

Once that decision is made, then we can change all references to FAQs.

Once all the references to FAQs have changed, reorganizing the FAQ is an easy process of reorganizing the FAQ table of contents and moving sections around in the FAQ.

xexyl commented 6 days ago

We see the value in reorganizing the FAQ

Let's decide on how FAQs should be externally referenced, given the constraints in the top comment soon.

Once that decision is made, then we can change all references to FAQs.

Once all the references to FAQs have changed, reorganizing the FAQ is an easy process of reorganizing the FAQ table of contents and moving sections around in the FAQ.

Glad you have decided reorganising it is a good idea, after all! I think it'll help. I cannot look at that comments right now but maybe in a bit. I was actually hoping I could have done something by now but not having much luck yet. I will be going afk for a little bit soon and maybe when back I can focus more. At least it's still early.

One question I can pose now, however, is this. I think I brought it up before but this should come after #2006 but before the merge, right? In other words: I should still focus on the other one but if by chance I have the time or thought on some of this I can work on this too. Of course discussing it is also a good idea and obviously necessary first but the point is this is less important than the other one so it's okay if I kind of let this sit a bit (discuss but not do), right?

I'll be going afk now but I hope that when I'm back I can start looking at things better.

lcn2 commented 6 days ago

One question I can pose now, however, is this. I think I brought it up before but this should come after #2006 but before the merge, right?

Yes.

And we might find a reason to add more FAQ. Better to reorganize after adding stuff.

In other words: I should still focus on the other one but if by chance I have the time or thought on some of this I can work on this too. Of course discussing it is also a good idea and obviously necessary first but the point is this is less important than the other one so it's okay if I kind of let this sit a bit (discuss but not do), right?

Sure. And a discussion here about how to reference the FAQs ahead of time (and before finishing issue #2006) might be useful too.

xexyl commented 6 days ago

One question I can pose now, however, is this. I think I brought it up before but this should come after #2006 but before the merge, right?

Yes.

And we might find a reason to add more FAQ. Better to reorganize after adding stuff.

Yes. Like the things I suggested yesterday .. or whenever it was. Monday if not yesterday.

In other words: I should still focus on the other one but if by chance I have the time or thought on some of this I can work on this too. Of course discussing it is also a good idea and obviously necessary first but the point is this is less important than the other one so it's okay if I kind of let this sit a bit (discuss but not do), right?

Sure. And a discussion here about how to reference the FAQs ahead of time (and before finishing issue #2006) might be useful too.

Well actually I was holding off on looking at the FAQ until everything else in #2006 is done for the very reason that things might be added or changed (and there have been numerous additions and changes) but yes it might be a good idea to talk about this ahead of that.

lcn2 commented 6 days ago

We believe we have addressed all of the current questions that still need answering at this time. If we've missed something or something else needs to be clarified, please ask again.

xexyl commented 6 days ago

Please feel free to remind me of this soon if I don't get to it. Have to go for the day.

xexyl commented 5 days ago

As far as some of the issues noted I either don't see it as a problem or I misunderstand. For instance:

Some "link text"s include a trailing ? (question mark).

What is the problem with a question mark when it's a question? Or is it more than one?

By:

Some "link text"s refer to the FAQ x.y number.

.. you mean not in the table of contents but down in the actual questions? What should it look like - for each part, the list and the questions themselves?

In fact what are link texts? Do you mean when linking TO it or the actual link that you are taken to when going to that question?

Maybe there are more that I'm not clear on but instead I'll say I'm not sure I see the problems in the relevant screenshots (or 'screenshots') section. Ah .. maybe that's the idea I had (I think I had it) where it should say something short that links TO the FAQ but not the FAQ file itself? Given that they're not in the faq.md itself I presume that's it.

If that's the case perhaps my questions above are not in the right context. The only one that would seem to not be a problem, maybe, is the question mark - it should I think?

That's all I can say for the time being but hopefully it starts some discussion. Hopefully tomorrow will be a day where I will be clearer. Will be having food soon probably and mostly done for the day.

xexyl commented 5 days ago

Okay I read again:

In regards to markdown links to FAQ entries:

... so definitely linking TO the FAQ and not in the FAQ itself. That's reason enough for me to stop for the day. I guess only one question I have above - the question mark one - is still relevant. Back tomorrow hopefully to work on the other issue but maybe I can fit some thoughts in this one too.

lcn2 commented 5 days ago

What is the problem with a question mark when it's a question? Or is it more than one?

If one wishes to reference a FAQ within some sentence, one may not want the FAQ link to contain a question mark. Punctuation is the preview of the sentence, not some FAQ link term that might appear within the sentence.

Say you wish to write the sentence:

The `.entry.json` file also contains refers to the "author handle" of the authors who wrote the entry.

Where the "author handle" is a link to the "FAQ 6.5: What is an author handle?" FAQ. It would create awkward punctuation if one simply inserted that FAQ string into the middle of that sentence:

The `.entry.json` file also contains refers to the ["FAQ 6.5: What is an author handle?"](faq.html#author_handle) of the authors who wrote the entry.

The FAQ punctuation (the quote marks and the final question mark) gets in the way of the sentence one is trying to construct. It is better to write:

The `.entry.json` file also contains refers to the [author_handle](faq.html#author_handle) of the authors who wrote the entry.

Let the FAQ link contain a sword or very short phrase. Let the sentence that needs to link to some FAQ control and select the punctuation it needs.

lcn2 commented 5 days ago

In fact what are link texts? Do you mean when linking TO it or the actual link that you are taken to when going to that question?

The link text is the string that is the link. For example:

This sentence has a [link text](http://example.com) in the middle of it.

The "link text" is the link text.

One does NOT want to put "FAQ 6.7" in some link text such as:

See the [FAQ 6.7](faq.html#entry_id) for more information about the syntax of an entry's identifying string.

If one needed to renumber that FAQ from 6.7 to, say 4.2 because one wanted to re-organize the FAQ, the presence of that "FAQ 6.7" would require that sentence of to modified when thr FAQ was re-organized.

Instead if one did:

See the "[entry id](faq.html#entry_id) FAQ" for more information about the syntax of an entry's identifying string.

There, without specifying the "6.7" FAQ number: reorganizing the FAQ would NOT require that sentence to be changed because heighten the "6.7" FAQ number is neither in the "link text", nor in the link URL.

And regarding the previous comment about not adding punctuation (neither the quotes nor the question mark): notice how the FAQ link text does NOT contain any punctuation. The sentence that contains the link to the FAQ is in full punctuation control.

xexyl commented 3 days ago

What is the problem with a question mark when it's a question? Or is it more than one?

If one wishes to reference a FAQ within some sentence, one may not want the FAQ link to contain a question mark. Punctuation is the preview of the sentence, not some FAQ link term that might appear within the sentence.

Say you wish to write the sentence:

The `.entry.json` file also contains refers to the "author handle" of the authors who wrote the entry.

Where the "author handle" is a link to the "FAQ 6.5: What is an author handle?" FAQ. It would create awkward punctuation if one simply inserted that FAQ string into the middle of that sentence:

The `.entry.json` file also contains refers to the ["FAQ 6.5: What is an author handle?"](faq.html#author_handle) of the authors who wrote the entry.

The FAQ punctuation (the quote marks and the final question mark) gets in the way of the sentence one is trying to construct. It is better to write:

The `.entry.json` file also contains refers to the [author_handle](faq.html#author_handle) of the authors who wrote the entry.

Let the FAQ link contain a sword or very short phrase. Let the sentence that needs to link to some FAQ control and select the punctuation it needs.

I agree with the quotes problem .. did not even know that was there. But the question mark - I think that depends on the item in question. I'm not sure what you mean by the examples though so it's harder to understand. Would you clarify what you mean by:

contains refers

(obviously a typo but I want to be sure before I try and parse what you're getting at.)

Thanks.

xexyl commented 3 days ago

In fact what are link texts? Do you mean when linking TO it or the actual link that you are taken to when going to that question?

The link text is the string that is the link. For example:

This sentence has a [link text](http://example.com) in the middle of it.

That is what I wondered and thought but wanted confirmation. Thanks. That does make sense.

The "link text" is the link text.

Thanks.

One does NOT want to put "FAQ 6.7" in some link text such as:

See the [FAQ 6.7](faq.html#entry_id) for more information about the syntax of an entry's identifying string.

I agree.

If one needed to renumber that FAQ from 6.7 to, say 4.2 because one wanted to re-organize the FAQ, the presence of that "FAQ 6.7" would require that sentence of to modified when thr FAQ was re-organized.

I agree.

Instead if one did:

See the "[entry id](faq.html#entry_id) FAQ" for more information about the syntax of an entry's identifying string.

There, without specifying the "6.7" FAQ number: reorganizing the FAQ would NOT require that sentence to be changed because heighten the "6.7" FAQ number is neither in the "link text", nor in the link URL.

Yes .. I suggested that a while back but of course I've only done a few as I've been working on the other html files that are higher priority.

And regarding the previous comment about not adding punctuation (neither the quotes nor the question mark): notice how the FAQ link text does NOT contain any punctuation. The sentence that contains the link to the FAQ is in full punctuation control.

Okay well yes with this change in place that indeed won't matter and the above comment does not need any clarification (with the typo).

I think this will be much nicer.

Am I right though in saying I should worry about the FAQ later on except that if I come across something that is relevant to the other issues I should (of course) update it?

What I have to do I noted in the issue about less obfuscated versions and one thing I did not note but need to do is to check the thanks file for those entries as they had to be changed some too. But since the idea of the directory name and maybe the Makefile has to be considered it might be better to wait before I do that anyway.

Off to do other things now. Hopefully tomorrow there will be some replies to some of the pending issues so more work can be done. Just going to take it easy the rest of the day I think.

lcn2 commented 15 hours ago

We believe we have addressed all of the current questions that still need answering at this time. If we've missed something or something else needs to be clarified, please ask again.