Enhancement: Reorganize the FAQ

[lcn2]

Is there an existing issue for this?

• [X] I have searched for existing issues and did not find anything like it

Describe the problem with or missing documentation

Now that links to FAQ items now involve URLs with “#string”s that do NOT involve FAQ numbers (apart from the FAQ table of contents),

and now that references to FAQ entries are of the form:

See the
FAQ on "[GitHub pull request](#pull_request)"
for more information about pull requests.

It is time to reorganize the FAQ into better sections and to rebuild FAQ table of contents accordingly.

Relevant files

faq.md

What you expect

The most important FAQs will at the top of the FAQ. These most important FAQs will be a select few relating to entering the IOCCC.

Other FAQs will be organized into suitable sections below.

Relevant links or files

faq.html

Anything else?

What is currently in FAQ “Section 0”, while all FAQ items in section 0 are useful, is too long. Someone who is impatient to enter IOCCC28 should not have to wade through items such as “How to validate any JSON document”. While that FAQ is informative, is unlikely to be needed by most people who are simply wanting to understand how to enter the IOCCC.

The current FAQ structure, while informative and potentially interesting to someone who is into the details of the IOCCC, is a potentially intimidating barrier to new people wishing to simply enter the IOCCC.

There should be a clear distinction between a few select and short “TL;DR” type FAQs relating to entering the FAQ, and those FAQs that relate to small or somewhat internal IOCCC details.

[lcn2]

QUESTION

What are the bare minimum FAQs that are really needed by someone who wishes to enter the IOCCC?

The top FAQ section should just contain that bare minimum set. Perhaps that top FAQ section be called something along the lines of "TL;DR Entering the IOCCC - a quickstart guide"? Then a later FAQ section could contain other sections current section 0 stuff and be called something along the lines of "More details about entering the IOCCC". Those are just suggestions.

The contents of each FAQ entry in the top bare minimum "TL;DR" set should be very short, preferably FAQ content that fits within a "single screen". If the contents of one of these "TL;DR" entries is too long, then more verbose part of that bare minimum FAQ should be moved into another FAQ (perhaps in the so-called "More details about entering the IOCCC" section), along with a "see also" link/reference to that more detailed content.

There is nothing wrong with an FAQ entry that goes into great detail with the FAQ. Such long and detailed FAQs, however, should not be part of the bare minimum FAQ "TL;DR" set.

Obviously the rest of the FAQ set needs to be reorganized and perhaps retitled too.

Other long and detailed FAQs elsewhere in the FAQ may wish to be also broken up into two FAQs: one for the high level summary that contains a "see also" link/reference to that more detailed content in a subsequent FAQ.

[lcn2]

This issue is a top priority and is required to be completed before the Great Fork Merge. This issue is essentially part of issue #2006 and is of equal importance to that work.

We simply broke this out from the critical top priority issue #2006 to make it easier to discuss FAQ related issues.

[xexyl]

Okay the reason I have not done this yet is because I figure I might end up having to modify the FAQ when I work on the entries that I have not yet finished.

The same goes for the bugs file though I'm also looking at that with each entry.

You can assign this to me though I agree it is part of #2006 and will be done after the entries' html files have been fixed/checked.

Now that we'll have a code freeze in mkiocccentry I hope to get back to this repo.

[xexyl]

Please add to the todo something about adding an entry to the FAQ about Zlib. The entry that requires it and should be updated to link to this new FAQ is 2012/vik.

I am aiming to finish 2012 today too. Not sure if I should go beyond that as I'm having a hard time seeing but my idea that I mentioned in the other one, about a deadline, is helping.

Thanks!

[xexyl]

Also would you please add an FAQ about IOCCC BOF? I know what it stands for but that's about it - but you also refer to it in several README.md files so it'd be nice if it could be linked to.

Thanks.

[lcn2]

Regarding GH-issuecomment-2409531657 and GH-issuecomment-2409549155 see commit 4386b63a8d988b27515f43210e62d119863a1fad and commit 2557b0cf1de6e7c50ba75cfeb745057268740289.

[lcn2]

It is VERY IMPORTANT to understand and this issue is about reorganizing the table of contents and the sections under which existing FAQs reside.

This issue is NOT about rewriting entries, nor adding new FAQ entries. This issue is about reorganizing the existing set of FAQ entries. That includes the "TL;DR" section as suggested in the top level TODO.

Moreover, the default action should this issue be still open a day or two before 2024 Oct 29 is to leave the FAQ as it is now.

[xexyl]

It is VERY IMPORTANT to understand and this issue is about reorganizing the table of contents and the sections under which existing FAQs reside.

This issue is NOT about rewriting entries, nor adding new FAQ entries. This issue is about reorganizing the existing set of FAQ entries. That includes the "TL;DR" section as suggested in the top level TODO.

Moreover, the default action should this issue be still open a day or two before 2024 Oct 29 is to leave the FAQ as it is now.

I understand this. But it felt better to have this done before I start doing this. I hope I can get to this issue but obviously the entries are of higher priority!

[xexyl]

Making good progress on reorganising the FAQ.

I am starting out by removing the anchors of the form "faq[0-9] (not regexp of course) so that it's easier to move them. After things are in order if it is desired to have that for each FAQ it can be added back. Doing it this way will prevent a mess and make it much easier.

It is not clear to me at this point that we even necessarily need to number them since the text we link to is always a name. However the number could be of use anyway. Certainly the sections should be numbered which might suggest that each one should be numbered. The downside to that is it makes it harder to add a new FAQ that might fit above another in its section.

I'll be going afk now but when back I'll continue. Once I have the links sorted (involving making new anchors too) I can test them on my server and then if that's good then I can worry about reordering things (possibly with new sections - or not .. that has to be determined still).

I do hope to finish this or mostly finish this today. I should have extra time today but I unfortunately also woke up earlier, albeit only half an hour earlier. Was up a bit later (or maybe it just felt like it, especially as I am more tired than usual) last night and likely tonight too but I probably was actually asleep at the usual time, it just feels later.

[xexyl]

Anything else?

What is currently in FAQ “Section 0”, while all FAQ items in section 0 are useful, is too long. Someone who is impatient to enter IOCCC28 should not have to wade through items such as “How to validate any JSON document”. While that FAQ is informative, is unlikely to be needed by most people who are simply wanting to understand how to enter the IOCCC.

I agree that many are quite long. Some need to be - if we want to keep them. Do we need to document the .info.json and .auth.json files? What about the .entry.json files? Maybe yes, maybe no. Those FAQs are quite long though and might benefit with a TL;DR, if we keep them.

QUESTION

I think it might be g good to remove the how to validate the JSON FAQ. If you agree I'll do that but not now.

Do you think it should be removed? It kind of seems out of scope to me.

I'm working on the anchor names. If that goes well I will then work on reordering things. Whether I do a pull request when it's incomplete (reordering wise) I do not know.

As I noted I am for now removing the numbers as we don't refer to them anyway and it is a burden when trying to reorganise and worse - mostly important later on - adding to the list, if that ever is necessary. I guess it might be necessary though most likely it'll be rare.

The current FAQ structure, while informative and potentially interesting to someone who is into the details of the IOCCC, is a potentially intimidating barrier to new people wishing to simply enter the IOCCC.

That's true. The question is what should be removed and what should be kept? The ordering of course is another matter entirely and will take quite some work.

There should be a clear distinction between a few select and short “TL;DR” type FAQs relating to entering the FAQ, and those FAQs that relate to small or somewhat internal IOCCC details.

Please elaborate on this. A clear distinction between ... I'm not clear on what you're getting at.

Thanks.

---

I do want to make sure I can work on the bugs file and clean up (and hopefully shorten, perhaps a lot) the thanks file, too, but I guess the FAQ is far more important so I'm trying to work on it first. Nonetheless it's going to take a tremendous amount of work, unfortunately, and I'm running out of time to meet the deadline.

[xexyl]

If we do keep the how to validate json files though....

Perhaps it belongs as a footnote to one of the other FAQs? I don't know though: might not be possible to make it short enough as a foot note.

I'm mixed on this. Certainly we should have an entry (and we do) for chkentry but are others necessary? Later on when it validates .entry.json files we certainly can get rid of it. BUT on the other hand it might be good to know anyway as the script in make test actually does use it. It shows where to get it (the copy in mkiocccentry which is good because it doesn't require installing the dbg and dyn_array libraries separately and it is consistent with the mkiocccentry tools).

I don't know.

I'm happy to do what you wish but this comment is for discussion: even if it's just: 'it should be removed'.

[xexyl]

I just saw a picture of .. F. D. C. Willard. A Chocolate Point Siamese (or it looks like a Siamese)!

I also have a Chocolate Point Siamese and a Lynx Point as well (her son). The Chocolate Point is called Brownie but not strictly because she's a Chocolate Point. The reason is the first week we got her she was hiding (she was found outside a pound with her babies, starving herself to make sure they were okay, so she's always been extra cautious/timid). So not only the Chocolate Point but also brownies in folklore.

Here's a picture of her:

She hasn't been on the stair rail in a long time; this picture was taken 2020. Here's Smokey:

That was taken 10 October 2024.

Fun words for you:

• ailurophile - lover of cats
• ailurophobe - person afraid of cats
• ailurophobia - fear of cats
• ounce - another term for snow leopard (no not making that up)
• destruction - group of wild cats (no not making that up .. neither am I when I say a group of rhinos is called a crash)

[lcn2]

I think it might be g good to remove the how to validate the JSON FAQ. If you agree I'll do that but not now.

Do you think it should be removed? It kind of seems out of scope to me.

We agree that it is out of scope. Please remove and please remove any links/references to that FAQ.

UPDATE 0

Perhaps it belongs as a footnote to one of the other FAQs? I don't know though: might not be possible to make it short enough as a foot note.

That is a good option too.

[lcn2]

There should be a clear distinction between a few select and short “TL;DR” type FAQs relating to entering the FAQ, and those FAQs that relate to small or somewhat internal IOCCC details. Please elaborate on this. A clear distinction between ... I'm not clear on what you're getting at.

Thanks.

Someone who just wants to know the basics of participating / submitting to the IOCCC does NOT want to wade through a lot of FAQ detail, however interesting and informative those FAQ details might be to others.

The "TL;DR" section (or whatever it is called) should contain just a few critical FAQ entries with only a brief sentence or 2 or 3. Short and to the point FAQ entries with just the high level details. These critical FAQs can, if needed, have a "see also link" to a lower down FAQ that can provide mode details if needed.

Critical / high level / "TL;DR" FAQs should be at the very top of the FAQ. There should be just a few of them. The need to be short and easy to read, light on details and to the point.

Someone looking at the overall FAQ for the first time should have their eyes drawn to these new top "TL;DR" FAQs AND the remaining FAQs should be farther down in the FAQ file. There should be a clear header separation between the few critical "TL;DR" at the top, and the rest of the FAQ. Such a header separation could say something like "FAQs for those curious about the finer details", or something like that.

The "TL;DR" section name is also open for discussion: that is just a working title that may or may not be good enough for the final FAQ file.

The critical "TL;DR" section should be very short. Perhaps short enough to fit on a standard desktop screen (of reasonable size), if that is at all possible?

What should be in the critical "TL;DR"? Just a select few. Here is an initial guess (these are not in any particular order):

• What is the IOCCC?

• how to I submit my code the IOCCC?

• how do I register for the IOCCC?

• what are the IOCCC rules and guidelines?

• Where to go to get more help?

UPDATE 0

QUESTION

What do you think are the critical "TL;DR" FAQs? That is, what are the few things that someone might need to know about the IOCCC?

[xexyl]

BTW:

[xexyl]

I will reply to your comment later but possibly not until tomorrow. But I will have more time today. I just have to do something else first.

[xexyl]

I think it might be g good to remove the how to validate the JSON FAQ. If you agree I'll do that but not now. Do you think it should be removed? It kind of seems out of scope to me.

We agree that it is out of scope. Please remove and please remove any links/references to that FAQ.

UPDATE 0

Perhaps it belongs as a footnote to one of the other FAQs? I don't know though: might not be possible to make it short enough as a foot note.

That is a good option too.

Hmm. Or perhaps the jparse repo should have an FAQ and it can link to that instead? Or if not an FAQ a section in the README.md? That would keep it clean and simple and those who really wanted to know could look at it. But the vast majority of people will only care about validating IOCCC specific JSON files and so when the chkentry tool is updated later on nobody will even need to use the jparse tool (itself).

What do you think about a link instead? I could just as well delete it though. I don't really mind: it might be useful to some who want to know but the FAQ is too long even if it has a lot of good content. Even if some people have no problem reading a lot (like us for example) that does not mean they would want to; they would rather read something that they enjoy. They want to find their question quickly and get the answer they need.

So either a link or delete that entry entirely. The only reason to keep the jparse reference there is due to make test. But most don't need to know that so this is why I suggest at most a link. Nothing more but perhaps less.

[xexyl]

There should be a clear distinction between a few select and short “TL;DR” type FAQs relating to entering the FAQ, and those FAQs that relate to small or somewhat internal IOCCC details. Please elaborate on this. A clear distinction between ... I'm not clear on what you're getting at. Thanks.

Someone who just wants to know the basics of participating / submitting to the IOCCC does NOT want to wade through a lot of FAQ detail, however interesting and informative those FAQ details might be to others.

The "TL;DR" section (or whatever it is called) should contain just a few critical FAQ entries with only a brief sentence or 2 or 3. Short and to the point FAQ entries with just the high level details. These critical FAQs can, if needed, have a "see also link" to a lower down FAQ that can provide mode details if needed.

Critical / high level / "TL;DR" FAQs should be at the very top of the FAQ. There should be just a few of them. The need to be short and easy to read, light on details and to the point.

Someone looking at the overall FAQ for the first time should have their eyes drawn to these new top "TL;DR" FAQs AND the remaining FAQs should be farther down in the FAQ file. There should be a clear header separation between the few critical "TL;DR" at the top, and the rest of the FAQ. Such a header separation could say something like "FAQs for those curious about the finer details", or something like that.

The "TL;DR" section name is also open for discussion: that is just a working title that may or may not be good enough for the final FAQ file.

The critical "TL;DR" section should be very short. Perhaps short enough to fit on a standard desktop screen (of reasonable size), if that is at all possible?

What should be in the critical "TL;DR"? Just a select few. Here is an initial guess (these are not in any particular order):

• What is the IOCCC?
• how to I submit my code the IOCCC?
• how do I register for the IOCCC?
• what are the IOCCC rules and guidelines?
• Where to go to get more help?

UPDATE 0

QUESTION

What do you think are the critical "TL;DR" FAQs? That is, what are the few things that someone might need to know about the IOCCC?

Before I give my feedback or even answer your question I want to make sure I follow you right. Then tomorrow morning I can reply (though I do have a phone call in the morning - doctor check-up, but likely I can reply before this as I wake up before it's even light out).

So... are you suggesting that there is a new section in the FAQ that are the most important things, like the list you give above, and then below that can be more detailed information (which some of the tl;dr FAQs might actually link to - or not)?

If you don't mean that what do you mean please? (I think the list you gave is reasonable to start out with though certainly but depending on if I follow you right, and I'm pretty sure I do but want to be certain, I might not have many suggestions.)

Thanks and best wishes on your recovery! I'll be back tomorrow.

[lcn2]

So... are you suggesting that there is a new section in the FAQ that are the most important things, like the list you give above, and then below that can be more detailed information (which some of the tl;dr FAQs might actually link to - or not)?

Yes. See GH-issuecomment-2418145374 for details.

[xexyl]

So... are you suggesting that there is a new section in the FAQ that are the most important things, like the list you give above, and then below that can be more detailed information (which some of the tl;dr FAQs might actually link to - or not)?

Yes. See GH-issuecomment-2418145374 for details.

This link is to my comment about validating JSON documents?

I guess you meant to make it the one I was replying to initially?

I will look at it sometime this morning. In a short bit of time I have to go away for a bit but I hope to make much more progress today on the FAQ.

I also want to quickly look at an entry of mine to see if I can simplify the try section.

Anyway now that you confirmed my thought I will be able to address your questions better.

Hope you're feeling better today!

[xexyl]

I'm currently pondering what to call the top level section ... going afk a bit. I'll have some thoughts later on. One candidate is 'How to enter the IOCCC: the bare minimum'.

But it might be also useful or a new document, somewhere, if possible? I'm not sure where it would fit though, so maybe not. I do think that the guidelines and rules should both link to the FAQ, however, probably towards the top. I can do that too.

These are general notes for me. I doubt I'll be afk long if at all but even if I'm not afk now I will be afk in a little bit.

[lcn2]

But it might be also useful or a new document, somewhere, if possible?

No new files, please. Now is not the time to start adding new FAQ files.

I'm not sure where it would fit though, so maybe not. I do think that the guidelines and rules should both link to the FAQ, however, probably towards the top. I can do that too.

Please 🙏 do not overthink this. Keep it simple please.

The "TL;DR" is simply the top block of FAQs with a name that implies these are the quick or most common FAQs for those who wish to join the IOCCC .. followed by a visual separator (such as a level one heading), followed by the rest of the FAQ.

Something like that. It can be done in markdown. Nothing special needed.

UPDATE 0

I'm currently pondering what to call the top level section ... going afk a bit. I'll have some thoughts later on. One candidate is 'How to enter the IOCCC: the bare minimum'.

Perhaps in markdown, something like:

# HOW TO ENTER THE IOCCC

Or:

# HOW TO ENTER THE IOCCC - the basics

Or even better:

# HOW TO ENTER THE IOCCC - TL;DR 

What would follow are those few, short, important FAQs. Hopefully short enough to be viewed as a whole in a glance with minimal scrolling needed if possible (it may not be possible, but that's a nice target 🎯 goal 🥅 ).

That would be followed by another level 1 markdown header such as:

# FAQ - THE REST OF THE STORY 

or something like that.

[xexyl]

No worries. Already figured it out. Will have a pull request later on.

[xexyl]

Once you merge https://github.com/ioccc-src/temp-test-ioccc/pull/2702/commits/330ebccc76c3e5a0f1f92573110d5eb149a1357e and can look at the table of contents we can go from there.

I did notice that some sections could probably be removed or greatly simplified. For instance the how to enter section talks about the mkiocccentry toolkit so couldn't the sections of what it is and how to use it be reduced somewhat? I don't know. On the one hand I'm afraid to not have enough information but on the other too much can be a problem. But then the guidelines also talk about how to use it so maybe this is not needed? Well we can look at it and discuss it.

I have to do something else now. If I have time I will look at the bugs or thanks file. Otherwise I'll continue tomorrow. I guess that's what'll happen.

[xexyl]

Please take a look at the new ordering of questions and let me know if you think anything should change.

Another thing crossed my mind but unfortunately it is not coming to me right now.

But if you get back on this tonight I can look at it tomorrow morning.

Of course if you want and can and iff you have the time and it's not too much to do you MAY move the questions to the right sections but I can also do that.

QUESTION

How should each question be labelled? For instance should it be prefixed with 'Q: '? Having numbers makes it harder to update but I guess it could be done after rearrangement is finished.

I am not looking at it now so I can't comment specifically but I do think that some questions could be either removed outright or drastically simplified. But determining which ones is complicated.

I am trying to get this done but I also have two other files that I need to look at.

Anyway hopefully after looking at the new sections and table of contents you will have some additional thoughts.

Thanks for feedback!

Have a great night!

[lcn2]

Please take a look at the new ordering of questions and let me know if you think anything should change.

At first glance faq.html looks much improved. Thank you @xexyl, this is very good progress.

Another thing crossed my mind but unfortunately it is not coming to me right now.

But if you get back on this tonight I can look at it tomorrow morning.

Of course if you want and can and iff you have the time and it's not too much to do you MAY move the questions to the right sections but I can also do that.

QUESTION

How should each question be labelled? For instance should it be prefixed with 'Q: '? Having numbers makes it harder to update but I guess it could be done after rearrangement is finished.

The Section markdown headers such as:

## Section 0: Entering the IOCCC: the bare minimum you need to know

is a good idea.

For the action FAQ entries, perhaps your idea of:

<div id="mkiocccentry">
### Q: What is the `mkiocccentry` tool and how do I use it?
</div>

is a good idea. However ...

UPDATE 0

A tricky thing to keep is that the table of contents order and the FAQs under the given section in the same order. We will need to be careful about this in the future.

Please check this. For example the "What types of entries have been frequently submitted to the IOCCC?" is in the wrong order.

Sadly this is a consequence of not using "FAQ x.y -" in the entries.

Another problem we see is that when one jumps down into the middle of the FAQ, on can get lost and not know which section the FAQ is in.

Perhaps instead of using "Q:" we should use "Q x.y:"? We know this is a reversal of a previous idea, however:

• it is easy to get lost in the middle of the FAQ
• it is hard to keep the FAQs in the same order as the table of contents

So perhaps we need:

<div id="mkiocccentry">
### Q 0.1: What is the `mkiocccentry` tool and how do I use it?
</div>

QUESTION about UPDATE 0

What do you think about this problem and how to solve it?

Should the entries in the table of contents also start with "Q x.y:"?

NOTE: If we do put "Q x.y" we would still NOT link to some "#x_y" tag. We would link to names such as "#mkiocccentry". Moreover when we refer/link to some FAQ, we would NOT use a "Q x.y". For example:

See the
FAQ on "[What is the `mkiocccentry` tool and how do I use it](#mkiocccentry)".

I.e., no "Q x.y" in the link name.

Given the problem of keeping the Table of Contents in the same order as the FAQ, and given the problem of getting lost in the middle of the FAQ, we think we need the "Q: x.y" in both the table of contents and the FAQ markdown level 3 text.

We know this is a reversal of a previous idea, but unless you have a better idea of how to solve this problem, we might have to do this.

Again, putting "Q x.y:" in the table of contents and in the FAQ markdown level 3 text does NOT mean we would use "faq_x_y" link tags, nor would we refer to an FAQ elsewhere by the "x.y".

UPDATE 1

Some of the entries in the table of contents do not end in a question mark ("?").

UPDATE 2

Section 3 "Compiling and running IOCCC entries" is too long.

We recommend this section should be divided into 2 sections somehow.

UPDATE 3

At the very bottom there are two "Jump to: top" entires. We suggest the short line and the end "Jump to: top" at the very end should be removed.

UPDATE 4

We think that Section 0 should have fewer entries.

Perhaps we need a "Section 1 - More entering the IOCCC details".

Then some of the Section 0 FAQs can be moved in that new Section 1.

For example, consider moving from Section 0 in the newly proposed "Section 1 - More entering the IOCCC details" these entries:

• Is there a way to not have to re-enter the same information, when making a change to my submission?
• May I use a different source or compiled filename than prog.c or prog?
• What are the IOCCC best practices for using markdown?
• How do I report bugs in an mkiocccentry tool?

Those FAQ are needed, but we need to keep the Section 0 set small.

[xexyl]

Please take a look at the new ordering of questions and let me know if you think anything should change.

At first glance faq.html looks much improved. Thank you @xexyl, this is very good progress.

Yes although (as noted below) I did NOT move the actual questions to the right order.

Another thing crossed my mind but unfortunately it is not coming to me right now. But if you get back on this tonight I can look at it tomorrow morning. Of course if you want and can and iff you have the time and it's not too much to do you MAY move the questions to the right sections but I can also do that. QUESTION How should each question be labelled? For instance should it be prefixed with 'Q: '? Having numbers makes it harder to update but I guess it could be done after rearrangement is finished.

The Section markdown headers such as:

## Section 0: Entering the IOCCC: the bare minimum you need to know

is a good idea.

I think it works for the name too.

For the action FAQ entries, perhaps your idea of:

<div id="mkiocccentry">
### Q: What is the `mkiocccentry` tool and how do I use it?
</div>

is a good idea. However ...

On the other hand so is ### FAQ: .... I guess. I don't know.

UPDATE 0

A tricky thing to keep is that the table of contents order and the FAQs under the given section in the same order. We will need to be careful about this in the future.

Yes.

Please check this. For example the "What types of entries have been frequently submitted to the IOCCC?" is in the wrong order.

Yes. As noted earlier that's because I did not want to worry about it until after the order of the table of contents is correct. So this was very intentional to save time. No sense doing it more than once.

Sadly this is a consequence of not using "FAQ x.y -" in the entries.

Actually it's not that. It's just that I did not bother to do that - yet. The problem with having numbers is it's harder to update. Makes it so if the order has to change all the numbers after it have to be changed too which is tedious and error prone. If one does not do it often it might be okay but still a burden.

Regardless the numbers should not be there until after the list is done.

QUESTION

It is a shame we cannot more easily use <ol>. Well we could in the table of contents now I think on it. But to do it in the FAQ itself we would have to add a <li> and <ol> and </ol> and </li> in the document itself. Maybe that would be worth it. What do you think?

Another problem we see is that when one jumps down into the middle of the FAQ, on can get lost and not know which section the FAQ is in.

That's true.

Perhaps instead of using "Q:" we should use "Q x.y:"? We know this is a reversal of a previous idea, however:

• it is easy to get lost in the middle of the FAQ
• it is hard to keep the FAQs in the same order as the table of contents

Well problem one is going to happen regardless.

Problem two is hard to make it the same order whether or not it's numbered. It's easy to find out which it should be under/above but it's tedious to actually move it. But one method of finding it is open it in the browser and then edit in in vim or in this case, since it takes some time (unless you have it in a reasonable enough order so you can do visual mode and then search to go down to it), use something like TextEdit. I actually did this for some parts yesterday until I had the thought that I should wait until the table of contents is sorted.

So perhaps we need:

<div id="mkiocccentry">
### Q 0.1: What is the `mkiocccentry` tool and how do I use it?
</div>

Maybe. See above for a thought that might make it easier. It would require more work to set up but once it's set up it would be ordered. Though I think the <ol> does not let one use 0 for the first number.

I can play with this in the table of contents and the sections too. A short section would be a good test case.

QUESTION about UPDATE 0

What do you think about this problem and how to solve it?

Depends on what problem. I gave a possible solution to the numbering problem. It would take a bit of time to set up but it would solve the annoying problem of ordering. Kind of. It wouldn't have the Q: x.y but it would have the numbered items.

I think that might be worth it. It would also make it easier in one way: we would still have to put the questions in the right order but we would not have to update every number manually.

Should the entries in the table of contents also start with "Q x.y:"?

I don't know. Using ordered lists like I suggested would simplify this. I'll play with this today.

NOTE: If we do put "Q x.y" we would still NOT link to some "#x_y" tag. We would link to names such as "#mkiocccentry". Moreover when we refer/link to some FAQ, we would NOT use a "Q x.y". For example:

Oh definitely true. That's why I changed it the other day.

See the
FAQ on "[What is the `mkiocccentry` tool and how do I use it](#mkiocccentry)".

I.e., no "Q x.y" in the link name.

Yes.

Given the problem of keeping the Table of Contents in the same order as the FAQ, and given the problem of getting lost in the middle of the FAQ, we think we need the "Q: x.y" in both the table of contents and the FAQ markdown level 3 text.

Sure but maintaining it is a pain. Unless my idea of ordered lists works well.

We know this is a reversal of a previous idea, but unless you have a better idea of how to solve this problem, we might have to do this.

See above.

Again, putting "Q x.y:" in the table of contents and in the FAQ markdown level 3 text does NOT mean we would use "faq_x_y" link tags, nor would we refer to an FAQ elsewhere by the "x.y".

Agreed.

UPDATE 1

Some of the entries in the table of contents do not end in a question mark ("?").

Good catch. I'll fix that today.

UPDATE 2

Section 3 "Compiling and running IOCCC entries" is too long.

Hmm ... I actually agree with this.

We recommend this section should be divided into 2 sections somehow.

Well using html lists would solve this problem, I think, as you can have lists in lists.

How would they be named though? My guess is that the sections would be (content wise, not name .. have to think about names):

0. Compiling the entries
1. Prerequisites to compile some entries.

Then another section would be:

Running the entries. Whether this is a subsection or not, or even whether the above two are subsections (perhaps not?) is unclear.

Maybe the names could be:

• How to compile winning IOCCC entries
• Resolving any dependencies (or 'Dependencies for some entries'? That sounds less good but the first one sounds kind of bad too)
• Running entries

Something like that.

As for making them subsections. I'm unsure. I think that dependencies belongs in the compiling section but perhaps the running the entries should be in its own section. The only reason to make the other one a subsection (or if it looks better) a new section is indeed because of the length. I'm mixed on the first two: I can see it both ways and the more I think on it the more I think making it another section might be a better way: exactly because it's already so long.

UPDATE 3

At the very bottom there are two "Jump to: top" entires. We suggest the short line and the end "Jump to: top" at the very end should be removed.

Very end of the DOCUMENT? Or of each section? As long as the end of each FAQ has a jump to top I don't see why the end of the document should have one too.

UPDATE 4

We think that Section 0 should have fewer entries.

Perhaps we need a "Section 1 - More entering the IOCCC details".

Perhaps the wording would be Section 1: more details on entering the IOCCC[0]

[0] I think that the table of contents should have the same character separator as the actual sections themselves. Whether that is : or - is unclear. I think the : looks nicer but that's me.

Then some of the Section 0 FAQs can be moved in that new Section 1.

For example, consider moving from Section 0 in the newly proposed "Section 1 - More entering the IOCCC details" these entries:

• Is there a way to not have to re-enter the same information, when making a change to my submission?
• May I use a different source or compiled filename than prog.c or prog?
• What are the IOCCC best practices for using markdown?
• How do I report bugs in an mkiocccentry tool?

Those FAQ are needed, but we need to keep the Section 0 set small.

I like that too.

Great feedback - thanks!

I'll play with the ordered lists soon (I hope). If this works then it's just a matter of having to set it up and then putting the questions in the correct order. But once that's done it'll be far easier to maintain.

[lcn2]

UPDATE 3

At the very bottom there are two "Jump to: top" entires. We suggest the short line and the end "Jump to: top" at the very end should be removed.

Very end of the DOCUMENT? Or of each section? As long as the end of each FAQ has a jump to top I don't see why the end of the document should have one too.

"At the very bottom there are two "Jump to: top" entires. "

[xexyl]

UPDATE 3 At the very bottom there are two "Jump to: top" entires. We suggest the short line and the end "Jump to: top" at the very end should be removed.

Very end of the DOCUMENT? Or of each section? As long as the end of each FAQ has a jump to top I don't see why the end of the document should have one too.

"At the very bottom there are two "Jump to: top" entires. "

So I thought. Thanks! Will do.

[xexyl]

I like the way the ordered list works! Check this screenshot:

This will greatly simplify things. All we have do once this is completely set up is to make sure in the content (not table of contents: the actual answers) add the appropriate <li></li> and at the end of each section have </ol> and beginning of each section have the <ol> and make sure to put the answer in the correct location.

I'll set this up today.

[lcn2]

Sure but maintaining it is a pain. Unless my idea of ordered lists works well.

Making and ordered list does not help as the Table of Contents order would be auto numbered in one order while the FAQ themselves might be auto numbered differently.

At least if you make in a "Q 2.4:" string in to both the table of contents and the FAQ, you set the order once correctly once and leave it that way. You set the order in the Table of Contents with "Q X.Y:" first, then jump down to the FAQ and set the same string there.

The ordered lists will renumber of things move around.

[lcn2]

I like the way the ordered list works! Check this screenshot:

This will greatly simplify things. All we have do once this is completely set up is to make sure in the content (not table of contents: the actual answers) add the appropriate <li></li> and at the end of each section have </ol> and beginning of each section have the <ol> and make sure to put the answer in the correct location.

You need a 2 level set of numbering, not just a single number.

[xexyl]

Sure but maintaining it is a pain. Unless my idea of ordered lists works well.

Making and ordered list does not help as the Table of Contents order would be auto numbered in one order while the FAQ themselves might be auto numbered differently.

At least if you make in a "Q 2.4:" string in to both the table of contents and the FAQ, you set the order once correctly once and leave it that way. You set the order in the Table of Contents with "Q X.Y:" first, then jump down to the FAQ and set the same string there.

The ordered lists will renumber of things move around.

It will. But without ordered lists we have to manually maintain it and also do make sure the order is correct. With ordered lists we just have to put the answer in the correct place.

[xexyl]

I like the way the ordered list works! Check this screenshot: This will greatly simplify things. All we have do once this is completely set up is to make sure in the content (not table of contents: the actual answers) add the appropriate <li></li> and at the end of each section have </ol> and beginning of each section have the <ol> and make sure to put the answer in the correct location.

You need a 2 level set of numbering, not just a single number.

Not sure why here but you can also do this with ordered lists. Done it many times.

[xexyl]

The benefit of ordered lists is it makes it MUCH easier to maintain. It will save time and energy. Once they are set up we have less to do. Without them we have more to do and it makes adding questions between others tedious and error prone. Not so with ordered lists.

[lcn2]

Not sure why here but you can also do this with ordered lists. Done it many times.

Fine with a "x.y" 2-level number ordered list.

You will still need to order the FAQs in the same way regardless.

[xexyl]

Not sure why here but you can also do this with ordered lists. Done it many times.

Fine with a "x.y" 2-level number ordered list.

You will still need to order the FAQs in the same way regardless.

Yes. You have to put the answers in the same location but you don't have to maintain the numbers. Just put them in the correct location and if it's in between others in the section you do not have to change all the numbers after it.

[xexyl]

The only downside is that in the answers themselves you don't see the section number per question. I think that might be worth it?

[lcn2]

The only downside is that in the answers themselves you don't see the section number per question. I think that might be worth it?

That's why your order list should be "X.Y", not just a counter.

[xexyl]

Now I can certainly roll that back but I don't fancy having to add the. numbers back. Certainly I won't do it until after the rest is done. But it seems like maintainability is far more important than having the x.y format.

[xexyl]

The only downside is that in the answers themselves you don't see the section number per question. I think that might be worth it?

That's why your order list should be "X.Y", not just a counter.

Yes but afaik that's not possible with html :(

Or am I unaware of something ?

[lcn2]

The only downside is that in the answers themselves you don't see the section number per question. I think that might be worth it?

That's why your order list should be "X.Y", not just a counter.

Yes but afaik that's not possible with html :(

Or am I unaware of something ?

Does markdown have an option?

[xexyl]

The only downside is that in the answers themselves you don't see the section number per question. I think that might be worth it?

That's why your order list should be "X.Y", not just a counter.

Yes but afaik that's not possible with html :( Or am I unaware of something ?

Does markdown have an option?

Not that I know of. Downside with it too is for markdown numbered lists you have to put the numbers in which you might as well do what we had before. So it would be no gain anyway, right?

[lcn2]

The only downside is that in the answers themselves you don't see the section number per question. I think that might be worth it?

That's why your order list should be "X.Y", not just a counter.

Yes but afaik that's not possible with html :( Or am I unaware of something ?

Does markdown have an option?

Not that I know of. Downside with it too is for markdown numbered lists you have to put the numbers in which you might as well do what we had before. So it would be no gain anyway, right?

perhaps this?

[xexyl]

The only downside is that in the answers themselves you don't see the section number per question. I think that might be worth it?

That's why your order list should be "X.Y", not just a counter.

Yes but afaik that's not possible with html :( Or am I unaware of something ?

Does markdown have an option?

Not that I know of. Downside with it too is for markdown numbered lists you have to put the numbers in which you might as well do what we had before. So it would be no gain anyway, right?

perhaps this?

But we would still have to put the numbers in manually so it would gain us nothing. That's the problem.

[lcn2]

Well try the HTML if that doesn't work.

[xexyl]

Well try the HTML if that doesn't work.

I'll do that. I have to go afk a bit. Maybe I can think of a hack. I also thought of another thing I have to do today. A medical thing, unfortunately. Fortunately it won't take that long though.

[xexyl]

I thought of a hack but unfortunately it doesn't work. The link you provided also in a comment suggests markdown doesn't support it but it would have the same problem as I noted anyway.

I thought of...

0\.<li><a class="normal" href="#submit">How can I enter the IOCCC?</a></li>

The \ was to try and escape any markdown rendering of it to make it a new line but unfortunately it doesn't work:

.. which is awful and useless. Maybe some CSS would allow to fix it?

[xexyl]

Okay the menu is organised better with numbers. Next step is to restructure the sections a bit also in the menu. After that I can make sure the answers are in the correct order. Once this is done I can then add the list items part. This is very tedious but I hope it'll be good. I also wish there was a way to do the x.y format but I do not know how sadly. They really should add that as a feature but even if they did it would take a long while (I guess) for it to be in most browsers.

[xexyl]

Please let me know how the new menu and answer/question numbering looks when commit b62dc414789a10f4034660a79784ff7531169994 is merged. Unfortunately I have a number of other things on my mind that makes it hard to do the next step of moving the questions to the right section and even adding the in the questions the new sections. So this is a big work in progress and just deals with the menu.

I do like how it looks but links have to be fixed too and some FAQs can be either removed or reduced in length drastically. I think I might have to do the bugs file sometime soon, maybe next, to make sure it gets done as the FAQ work is taking a lot of time and is quite error prone (it turns out).