Enhancement: Discuss man pages (+ other documentation) that have yet to be added (and those already added)

[xexyl]

I wasn't sure if this should be in the 'issues that aren't really issues' or not but I decided to make it a new issue for now as maybe there's enough to discuss that it warrants a new issue.

I think I know the answer but does every script need a man page? Every tool should have one but what about every script? Do we need any other man pages that aren't section 1?

Currently (as of 7 July 2022) running

$ for i in $(ls -1 *.{1,3}); do echo "- ${i}";done

(Maybe there's a more efficient way to do this but this is what came to my mind at 0223 ... but suggestions welcome please!)

Will give you:

• chkentry.1
• dbg.3
• fnamchk.1
• iocccsize.1
• jparse.1
• jstrdecode.1
• jstrencode.1
• limit_ioccc.1
• mkiocccentry.1
• old.chkauth.1
• old.chkinfo.1
• txzchk.1
• utf8_test.1
• verge.1

Now chkentry.1 is not complete because the tool is not yet written. The old.chk* will only be used in some concepts: the tools are no longer needed as chkentry will take their place.

As I said at the time I wasn't sure if limit_ioccc.sh's man page should be section 1 but I decided to make it that way because it can be used (and is used) in shell scripts via source (or .).

But there are many man pages that are missing too. What should be added? Should anything be changed in the man pages that exist?

I am very well aware of course that even if new discussion brings changes to any of these that prior to the repo being tested in the general public there might be some changes that are needed. Perhaps this issue should be left open until that is done? Certainly until all tools have man pages though. As new tools are added we can add more to discuss.

Maybe there's an easy way to come up with a list of missing man pages - I can possibly think of one - but I am trying to make this quick and discussing man pages that exist is also good.

BTW: I know I asked before and the answer then was 'no' but should there be html versions of the man pages at any point? It might be easy to convert to html via not using the -P option and redirecting to markdown files ... though of course maybe we'd have to make some manual edits. Or perhaps there's even a man2html ? I seem to recall there might be. Just a thought that might be worth thinking about on the website: or perhaps not. I leave that up to you but I'd be happy to help with it if you decide this is a good idea.

Going to try resting now .. hope you're having a nice sleep my good friend! I do have to be out later on today - post surgery doctor visit - but at that point I would be done here for the day anyway most likely. Did a small pull request. Not sure if I'll do more later on. We shall see. BCNU! :)

[lcn2]

BTW: I know I asked before and the answer then was 'no' but should there be html versions of the man pages at any point? It might be easy to convert to html via not using the -P option and redirecting to markdown files ... though of course maybe we'd have to make some manual edits. Or perhaps there's even a man2html ? I seem to recall there might be. Just a thought that might be worth thinking about on the website: or perhaps not. I leave that up to you but I'd be happy to help with it if you decide this is a good idea.

Probably for someone browsing the site, a markdown file for each man page might be nice. Github renders foo.md for you when you click on the line. For example dbg.md works.

However we don't want duplicate data: I.e., we don't want to have to edit foo.1 and foo.md in the same way each time. This is a current maintenance problem for dbg.3 and dbg.md. Both have to be maintained in parallel in exactly the same way. This is not a good idea as it will lead to divergent / conflicting documentation.

So if there was a way to generate foo.md form foo.1 (or the other way around?) then sure, lets add such a rule to the Makefile to build those files for a release.

However without such a man page / markdown translator, we would not recommend doing that too often.

Comments?

[lcn2]

But there are many man pages that are missing too. What should be added?

• hostchk.1
• iocccsize_test.1
• jparse_test.1
• jstr_test.1
• mkiocccentry_test.1
• prep.8
• reset_tstamp.8
• run_bison.1
• run_flex.1
• txzchk_test.1
• vermod.8
• dyn_array.3

Those come to mind for starters.

[lcn2]

Should anything be changed in the man pages that exist?

The FILES section content is probably not the best place for content that is ore along the lines of make depend: I.e., this FILES section shouldn't list source code files and header files.

For example, in iocccsize.1, the FILES section contains references a header file that does not exist (iocccsize.j). But even with that fix, listing header files means that the documentation has to change whenever the source code include tree change, and that is not helpful. In the case of iocccsize_test.sh, that tool should have a man page (see comment 1178856800) and so should be mentioned in a SEE ALSO section instead. With those cases, the FILES section of iocccsize.1 can go away: letting the source code and Makefile speck it itself. :-)

Not every FILES section needs to go away. For example, in jparse.1, the FILES section the json_teststr.txt is the providence of the jparse_test.sh tool and thus should be in the FILES section for a jparse_test.1 man page. The reference to jparse_test.sh in the jparse.1, the FILES section should instead be a SEE ALSO section as a parse_test.8 man page. For while there doesn't seem to be a call for the jparse.1 FILES section, there is for one in the jparse_test.1 man page.

If it is a "Source file of" or "Header file for", it probably should not be in the FILES section. if it is a reference to a test script, then that script should have its own man page and the reference should be in the SEE ALSO section.

[xexyl]

BTW: I know I asked before and the answer then was 'no' but should there be html versions of the man pages at any point? It might be easy to convert to html via not using the -P option and redirecting to markdown files ... though of course maybe we'd have to make some manual edits. Or perhaps there's even a man2html ? I seem to recall there might be. Just a thought that might be worth thinking about on the website: or perhaps not. I leave that up to you but I'd be happy to help with it if you decide this is a good idea.

Probably for someone browsing the site, a markdown file for each man page might be nice. Github renders foo.md for you when you click on the line. For example dbg.md works.

I think it would be nice too.

That's true that GitHub does that though I was thinking more for the IOCCC website. But maybe here is enough? I don't really know.

However we don't want duplicate data: I.e., we don't want to have to edit foo.1 and foo.md in the same way each time. This is a current maintenance problem for dbg.3 and dbg.md. Both have to be maintained in parallel in exactly the same way. This is not a good idea as it will lead to divergent / conflicting documentation.

Okay so is dbg.md necessary? I guess it is for the website but that's what I was wondering about in discussion a while back. Would it not be better if dbg.md was greatly reduced in length but referred to the man page?

So if there was a way to generate foo.md form foo.1 (or the other way around?) then sure, lets add such a rule to the Makefile to build those files for a release.

However without such a man page / markdown translator, we would not recommend doing that too often.

Comments?

I'm not sure if there is or isn't. I know there's a man2html though it's not perfect as it converts see also to links which is not what is needed here I think (It doesn't let you specify the path as far as I am aware).

I was thinking that it might be an idea after everything is sorted though?

[xexyl]

But there are many man pages that are missing too. What should be added?

• hostchk.1
• iocccsize_test.1
• jparse_test.1
• jstr_test.1
• mkiocccentry_test.1
• prep.8
• reset_tstamp.8
• run_bison.1
• run_flex.1
• txzchk_test.1
• vermod.8
• dyn_array.3

Those come to mind for starters.

Hmm yes and some of those I wouldn't have thought of needing man pages. I was going to say as for vermod.sh that's still not one I'm too familiar with the workings of it. That might not be necessary to know to write the man page but then it might also be. That's one of the reasons I've not worked on that one (though other things seemed more important too of course).

As for the dyn_array one I think that you should write that one as you know that system very well and I do not. I guess I could start it out but I feel like it might be better that you do the most of that one.

The same goes for the timestamp one and possibly the iocccsize one since you know these better.

I'm not sure about the prep one. I might be able to do that one. The others (esp the txzchk_test.sh one) I shouldn't have any problems with (though I will have to look a bit more a the run flex and bison scripts first I think).

I believe there might be some other tools that are missing though?

A question about vermod though. Why section 8 and not 1 when it's an executable? Is it because you view it as system management (or in this case repo management)?

Should any other scripts have the section changed in your mind? For example what about limit_ioccc ? I mentioned my uncertainty on that before and I think in the first post of this thread but in case: it seemed like 1 is okay because it's used in scripts. Yet it could also be viewed as (maybe - in some ways?) a configuration file. Loosely defined of course: it is generated from the limit_ioccc.h file and one cannot just change the limits without any thought but since it the script can be read in from scripts to get values some might view it as a configuration file. I don't know what your thoughts are on that.

[xexyl]

Should anything be changed in the man pages that exist?

The FILES section content is probably not the best place for content that is ore along the lines of make depend: I.e., this FILES section shouldn't list source code files and header files.

Interesting thought.

For example, in iocccsize.1, the FILES section contains references a header file that does not exist (iocccsize.j). But even with that fix, listing header files means that the documentation has to change whenever the source code include tree change, and that is not helpful. In the case of iocccsize_test.sh, that tool should have a man page (see comment 1178856800) and so should be mentioned in a SEE ALSO section instead. With those cases, the FILES section of iocccsize.1 can go away: letting the source code and Makefile speck it itself. :-)

Hmm yes that is a mistake indeed. So with iocccsize.1 the entire FILES sections should be removed?

What about others though? One way to go about is that only the ones that are absolutely part of it and will never change be listed. For example with txzchk only list the txzchk.h and txzchk.c file: nothing else. What about that?

jparse is probably the most complicated one though.

Not every FILES section needs to go away. For example, in jparse.1, the FILES section the json_teststr.txt is the providence of the jparse_test.sh tool and thus should be in the FILES section for a jparse_test.1 man page. The reference to jparse_test.sh in the jparse.1, the FILES section should instead be a SEE ALSO section as a parse_test.8 man page. For while there doesn't seem to be a call for the jparse.1 FILES section, there is for one in the jparse_test.1 man page.

Hmm... jparse_test.8 ? Why 8 ?

(NOTE: I refer to parse_test.8 which I guess was meant to be jparse_test.8 - but you also have jparse_test.1 so I'm not sure here. Please elaborate.)

Some of the above I'm not actually clear on. The first part of the paragraph I follow but for some reason not the second half. I'm not sure if that's how you worded it or if it's because I'm rather uncomfortable (physically) right now - from surgery.

I can try reading it later on (not sure if that'll be today but probably would be the next time I work on documentation) and if it isn't clear then I can ask you to elaborate/rephrase it.

If it is a "Source file of" or "Header file for", it probably should not be in the FILES section. if it is a reference to a test script, then that script should have its own man page and the reference should be in the SEE ALSO section.

I agree on the test script file yes. I'm not sure in all cases for the source file of / header file for. I mean I can remove those but for some I think it might be good to have. But then your idea is equally valid. So what I guess is needed is a yes or no: should ALL the source file / header files for ALL (or some?) of the man pages be removed? If not yes entirely what should be kept?

Going to do something else now and probably won't work on the repo more today. Hope you have a great day! If you reply to things I should be able to get back to that depending on the time and how my day is going. Good day!

[xexyl]

An interesting variation of the files being updated or missing or being renamed I discovered a short bit ago. I have the fix already in place for a commit (but not today) but it made me think I should mention it here too since it's kind of related - even if not related to documentation it is related to missing files.

See the following git diff:

$ git diff jstr_test.sh
diff --git i/jstr_test.sh w/jstr_test.sh
index e64abe7..d32e94b 100755
--- i/jstr_test.sh
+++ w/jstr_test.sh
@@ -84,12 +84,12 @@ else
 fi
 
 # test some text holes in the encoding and decoding pipe
 #
 echo "$0: about to run test #6"
-export SRC_SET="jstr_test.sh dbg.c dbg.h fnamchk.c iocccsize.c chkauth.c"
-SRC_SET="$SRC_SET chkinfo.c json_parse.c json_parse.h jstrdecode.c jstrencode.c"
+export SRC_SET="jstr_test.sh dbg.c dbg.h fnamchk.c iocccsize.c"
+SRC_SET="$SRC_SET chkentry.c json_parse.c json_parse.h jstrdecode.c jstrencode.c"

The question is: what is the purpose of using SRC_SET and should the files list be generated automagically? We can't do that with man pages (well maybe with m4 magic? - but that's just an idea that popped into my head very briefly and I have given it no thought whatever) but there might be other places (like this script) where it can be done. Should it though?

And with that I'm done here. Going to get some food and then will just take it easy a bit longer and then try sleeping. It's been a difficult day.

[lcn2]

That's true that GitHub does that though I was thinking more for the IOCCC website. But maybe here is enough? I don't really know.

The IOCCC website is on GitHub, which is why GitHub's markdown rendering will be relevant.

We plan to remove the old HTML duplicates of stuff on the IOCCC web site and use markdown files and GitHub's rendering of them.

[xexyl]

That's true that GitHub does that though I was thinking more for the IOCCC website. But maybe here is enough? I don't really know.

The IOCCC website is on GitHub, which is why GitHub's markdown rendering will be relevant.

We plan to remove the old HTML duplicates of stuff on the IOCCC web site and use markdown files and GitHub's rendering of them.

Interesting. Somehow that kind of disappoints me - but maybe that's a nostalgia thing. Not sure. But then I also haven't seen it yet so maybe it's fine. We shall see I guess but I'm sure you've given it a lot of thought anyway so it'll work out.

EDIT: Ah. Maybe you mean you'll take GitHub's html files and put them on the old IOCCC website? That's an interesting thought too.

[lcn2]

Okay so is dbg.md necessary? I guess it is for the website but that's what I was wondering about in discussion a while back. Would it not be better if dbg.md was greatly reduced in length but referred to the man page?

You raise a good point. The dbg.md file probably should reference the dbg(3) man page in the way you did for the README.md of this repo.

Recall that the dbg facility is hosted on dbg repo. The repo needs a README.md file, which is what dbg.md in intended to convey. We cannot call it README.md because that filename was already taken :) :) :) so instead it was called dbg.md. When the files are copied into the dbg, the file is renamed (from dbg.md to README.md).

[xexyl]

Okay so is dbg.md necessary? I guess it is for the website but that's what I was wondering about in discussion a while back. Would it not be better if dbg.md was greatly reduced in length but referred to the man page?

You raise a good point. The dbg.md file probably should reference the dbg(3) man page in the way you did for the README.md of this repo.

Yes. But how it does so is another matter entirely.

Recall that the dbg facility is hosted on dbg repo. The repo needs a README.md file, which is what dbg.md in intended to convey. We cannot call it README.md because that filename was already taken :) :) :) so instead it was called dbg.md. When the files are copied into the dbg, the file is renamed (from dbg.md to README.md).

True. I'm still not clear on the conflict you refer to in the other repo but I gave a solution to that as well. Otherwise I can fix it tomorrow or the next day.

[lcn2]

That's true that GitHub does that though I was thinking more for the IOCCC website. But maybe here is enough? I don't really know.

The IOCCC website is on GitHub, which is why GitHub's markdown rendering will be relevant.
We plan to remove the old HTML duplicates of stuff on the IOCCC web site and use markdown files and GitHub's rendering of them.

Interesting. Somehow that kind of disappoints me - but maybe that's a nostalgia thing. Not sure. But then I also haven't seen it yet so maybe it's fine. We shall see I guess but I'm sure you've given it a lot of thought anyway so it'll work out.

EDIT: Ah. Maybe you mean you'll take GitHub's html files and put them on the old IOCCC website? That's an interesting thought too.

The writeup will be a single URL per entry. We could go the other way and generate the HTML from markdown as well. This is TBD.

[xexyl]

That's true that GitHub does that though I was thinking more for the IOCCC website. But maybe here is enough? I don't really know.

The IOCCC website is on GitHub, which is why GitHub's markdown rendering will be relevant.
We plan to remove the old HTML duplicates of stuff on the IOCCC web site and use markdown files and GitHub's rendering of them.

Interesting. Somehow that kind of disappoints me - but maybe that's a nostalgia thing. Not sure. But then I also haven't seen it yet so maybe it's fine. We shall see I guess but I'm sure you've given it a lot of thought anyway so it'll work out.
EDIT: Ah. Maybe you mean you'll take GitHub's html files and put them on the old IOCCC website? That's an interesting thought too.

The writeup will be a single URL per entry. We could go the other way and generate the HTML from markdown as well. This is TBD.

One concern (from the sound of it): what about people who write a lot or want to organise different things in more than one file? For example with Snake I have an entire document dedicated to different gameplay modes but the general remarks is shorter (though not necessarily short). In that entry I also have a file for spoilers (on obfuscation) and various other files.

In the Enigma machine I have the obfuscation details enciphered via the actual machine itself!

In weasel words of 2018 I have more of it in one file but I still have more than one file of details.

I know I'm more of an exception with documentation (though that's only for the contest) but even so it's something to keep in mind. But maybe you're working on this too.

[lcn2]

Okay so is dbg.md necessary? I guess it is for the website but that's what I was wondering about in discussion a while back. Would it not be better if dbg.md was greatly reduced in length but referred to the man page?

Yes,. the dbg.md is the README.md for the dbg repo.

If it helps: perhaps dbg.md should be dropped from this repo altogether. The README.md file is what is needed in THAT repo, not dbg.md in this repo.

We suggest you focus on pull requests in the dbg repo, and then copy over dbg.c and dbg.h from that repo into this repo.

BTW: For a similar reason, we might want to drop dbg_example.c in this repo and let dbg_example.c exist in the dbg repo.

So may we suggest:

UPDATE 0:

• update README.md in the dbg repo if and when needed
• update dbg_example.c in the dbg repo if and when needed
• update dbg.3 in the dbg repo if and when needed
• remove dbg.md in the mkiocccentry repo
• remove dbg_example.c in the mkiocccentry repo
• after updating, copy dbg.c from the dbg repo to dbg.c in the mkiocccentry repo
• after updating, copy dbg.h from the dbg repo to dbg.h in the mkiocccentry repo
• after updating, copy dbg.3 from the dbg repo to dbg.3 in the mkiocccentry repo

[lcn2]

I'm not sure if there is or isn't. I know there's a man2html though it's not perfect as it converts see also to links which is not what is needed here I think (It doesn't let you specify the path as far as I am aware).

We guess that someone who needs to read a man page such as dyn_array(3) or reset_tstamp(8) is a programmer / developer, not someone who is casually browsing with a web browser. As such, they would use the man(1) command on a command line .. or use a browser plugin to render the man page. Someone looking into the finer details of txzchk_test(1) is someone who is looking deep into code, not browsing the README.md file of the repo with a web browser.

[xexyl]

Okay so is dbg.md necessary? I guess it is for the website but that's what I was wondering about in discussion a while back. Would it not be better if dbg.md was greatly reduced in length but referred to the man page?

Yes,. the dbg.md is the README.md for the dbg repo.

If it helps: perhaps dbg.md should be dropped from this repo altogether. The README.md file is what is needed in THAT repo, not dbg.md in this repo.

We suggest you focus on pull requests in the dbg repo, and then copy over dbg.c and dbg.h from that repo into this repo.

BTW: For a similar reason, we might want to drop dbg_example.c in this repo and let dbg_example.c exist in the dbg repo.

So may we suggest:

• update README.md if and when needed
• update dbg_example.c if and when needed
• update dbg.c if and when needed
• update dbg.h if and when needed
• update dbg.3 if and when needed
• remove dbg.md in this repo
• remove dbg_example.c in this repo
• after updating, copy dbg.c to dbg.c in this repo
• after updating, copy dbg.h to dbg.h in this repo
• after updating, copy dbg.3 to dbg.3 in this repo

I'll have to look at this later - not today. I'm having a hard time focusing my eyes and I'll be off soon for the night. But from what I gather this is probably a good idea yes.

[xexyl]

I'm not sure if there is or isn't. I know there's a man2html though it's not perfect as it converts see also to links which is not what is needed here I think (It doesn't let you specify the path as far as I am aware).

We guess that someone who needs to read a man page such as dyn_array(3) or reset_tstamp(8) is a programmer / developer, not someone who is casually browsing with a web browser. As such, they would use the man(1) command on a command line .. or use a browser plugin to render the man page. Someone looking into the finer details of txzchk_test(1) is someone who is looking deep into code, not browsing the README.md file of the repo with a web browser.

This is probably true for many of the man pages yes. Perhaps that's enough given that there might not be a better option. And actually I think man2html does have that option to open it in a browser so they could do that too.

I guess then we can say that it's probably not needed to have html files for all the man pages? What about other documentation file types? (Not sure what those might be - just saying that in case there is something now or in the future.)

[lcn2]

The content of README.md is currently focused on repo developers. That is OK, for developers. However the majority of people who will use this repo are IOCCC contestants wanting to enter the IOCCC. They just want to know how to do what they need to do in order to package their entry.

So README.md should address the needs of someone who wants to submit to the IOCCC.

This isn't to say that the current contents of README.md are unwanted. That content is useful, but perhaps not as a README.md for this repo.

Maybe the current contents of README.md should be put into developer.md or some such file?

While it is true that people who enter the IOCCC are, by their very nature, developers. Such people are probably not developers of the code in mkkioccentey repo.

Please consider moving the contents of README.md info another file (developer.md perhaps?) and then rewriting README.md to focus on what someone needs to do in order to package their entry for the IOCCC. This new README.md contents can, towards the end, suggest those who are curious about the code in this repo could look at developer.md. The new README.md contents, towards the end, should mention what to do if they have problems compiling this code (this is where the make report - issue #248 comes into play). But the primary focus of README.md is to be a TL;DR for someone who wants to package and entry for the IOCCC.

[xexyl]

The content of README.md is currently focused on repo developers. That is OK, for developers. However the majority of people who will use this repo are IOCCC contestants wanting to enter the IOCCC. They just want to know how to do what they need to do in order to package their entry.

So README.md should address the needs of someone who wants to submit to the IOCCC.

This isn't to say that the current contents of README.md are unwanted. That content is useful, but perhaps not as a README.md for this repo.

Maybe the current contents of README.md should be put into developer.md or some such file?

While it is true that people who enter the IOCCC are, by their very nature, developers. Such people are probably not developers of the code in mkkioccentey repo.

Please consider moving the contents of README.md info another file (developer.md perhaps?) and then rewriting README.md to focus on what someone needs to do in order to package their entry for the IOCCC. This new README.md contents can, towards the end, suggest those who are curious about the code in this repo could look atdeveloper.md. The new README.md contents, towards the end, should mention what to do if they have problems compiling this code (this is where the make report - issue #248 comes into play). But the primary focus of README.md is to be a TL;DR for someone who wants to package and entry for the IOCCC.

This is a great idea actually. I'll have to look at it in more detail - hopefully in the coming days. I suspect that this will require some discussion as well but that's okay. I'll hopefully get to this soon.

[lcn2]

That's true that GitHub does that though I was thinking more for the IOCCC website. But maybe here is enough? I don't really know.

The IOCCC website is on GitHub, which is why GitHub's markdown rendering will be relevant.
We plan to remove the old HTML duplicates of stuff on the IOCCC web site and use markdown files and GitHub's rendering of them.

Interesting. Somehow that kind of disappoints me - but maybe that's a nostalgia thing. Not sure. But then I also haven't seen it yet so maybe it's fine. We shall see I guess but I'm sure you've given it a lot of thought anyway so it'll work out.
EDIT: Ah. Maybe you mean you'll take GitHub's html files and put them on the old IOCCC website? That's an interesting thought too.

The writeup will be a single URL per entry. We could go the other way and generate the HTML from markdown as well. This is TBD.

One concern (from the sound of it): what about people who write a lot or want to organise different things in more than one file? For example with Snake I have an entire document dedicated to different gameplay modes but the general remarks is shorter (though not necessarily short). In that entry I also have a file for spoilers (on obfuscation) and various other files.

In the Enigma machine I have the obfuscation details enciphered via the actual machine itself!

In weasel words of 2018 I have more of it in one file but I still have more than one file of details.

I know I'm more of an exception with documentation (though that's only for the contest) but even so it's something to keep in mind. But maybe you're working on this too.

The entry can create its own fun documentation and stuff. That is one of the reasons for all of those extra files are allowed.

We are taking about the title page of the entry. There needs to be a single URL where someone can view the judges writeup, along with selected notes from the author. For that title page of we don't need the same data in two or more different forms: we just need one URL.

There needs to be a focus on simplicity of maintaining the IOCCC web site. The complexity and over engineered design of the web site is WHY the IOCCC was delayed sooooooo mmaaaannnnyyy times. It is often why the IOCCC skipped a year. It is why Simon is no longer part of the IOCCC: too much focus on an organization of web site, not enough on judging.

We are mindful that the rebuild of the IOCCC web site is a big task that MUST be done before the IOCCCMOCK can happen, let alone holding the next IOCCC. We need to finalize the JSON parser semantics test code and return to editing the IOCCC web site.

UPDATE 0a

Simplicity of maintenance of the process is vital in order to streamline the holding and running of the IOCCC.

Until the IOCCC web site maintenance is brought under control, the next IOCCC will be stalled waiting to be help. The complexity of the existing tools that maintained the IOCCC web site caused the IOCCC to collapse into a heap.

The solution to maintaining and rebuilding the IOCCC web site will be JSON files. A JSON file for each IOCCC author, and a JSON file for each winning entry. Those JSON files will grab data from the .info.json and .author.json files, with a few extra stuff added for the given IOCCC.

The title page of a winning entry will be formed, in part, from the JSON files for the winners and their entry, along with the contents of the judges remarks and selected remarks from the authors.

The title page of a winning entry will refer to the manifest (JSON file for each winning entry that in turn came from the manifest array .info.json), etc.

So if the entry has a bunch of fun ways to provide documentation, it can so do. References to those files will be shown in the manifest of the JSON file the each winning entry. Moreover, the judges remarks and/or selected remarks from the authors can further point to fun documentation that entry might provide.

Winning authors will be able to submit pull requests against their JSON winners file and JSON file for the winning entry. They can submit pull requests against the judges remarks and selected remarks from the authors ... plus changes to the enter itself. However the title page will be auto generated from content.

BTW: It is likely that the title page will be index.html for the winning entry directory. This is why we are moving to a one directory per winning entry model for the web site.

[xexyl]

That's true that GitHub does that though I was thinking more for the IOCCC website. But maybe here is enough? I don't really know.

The IOCCC website is on GitHub, which is why GitHub's markdown rendering will be relevant.
We plan to remove the old HTML duplicates of stuff on the IOCCC web site and use markdown files and GitHub's rendering of them.

Interesting. Somehow that kind of disappoints me - but maybe that's a nostalgia thing. Not sure. But then I also haven't seen it yet so maybe it's fine. We shall see I guess but I'm sure you've given it a lot of thought anyway so it'll work out.
EDIT: Ah. Maybe you mean you'll take GitHub's html files and put them on the old IOCCC website? That's an interesting thought too.

The writeup will be a single URL per entry. We could go the other way and generate the HTML from markdown as well. This is TBD.

One concern (from the sound of it): what about people who write a lot or want to organise different things in more than one file? For example with Snake I have an entire document dedicated to different gameplay modes but the general remarks is shorter (though not necessarily short). In that entry I also have a file for spoilers (on obfuscation) and various other files.
In the Enigma machine I have the obfuscation details enciphered via the actual machine itself!
In weasel words of 2018 I have more of it in one file but I still have more than one file of details.
I know I'm more of an exception with documentation (though that's only for the contest) but even so it's something to keep in mind. But maybe you're working on this too.

There needs to be a focus on simplicity of maintaining the IOCCC web site. The complexity and over engineered design of the web site is WHY the IOCCC was delayed sooooooo mmaaaannnnyyy times. It is often why the IOCCC skipped a year. It is why Simon is no longer part of the IOCCC: too much focus on an organization of web site, not enough on judging.

Aha. Well I probably was the first one (besides you and Leo of course) to know - he mailed me right after publication of the 2020 entries. I would have asked if he was okay but he told me all was well so I did not worry. I think I saw him make a comment on hacker news since then about the contest (about formatting of code and not any tips or anything like that). I was going through a pretty rough time then and he wished me well as well. But I didn't know why he retired.

I will reply to the other things later - hopefully tomorrow. I had to go help my mum with her iPad but now I'm going to get ready to sleep. Hope you have a good night my friend!

[lcn2]

We looked at man2html v3.0.1 (also available on macOS via homebrew) ...

With commit 04df879

Added man2html rule

Because there is sometimes a more convenient ways to read documentation.

UPDATE 0

We have a suggestion, @xexyl for you:

The make man2html rule is a tad bit long. Perhaps you should form a man2html.sh tool that checks for man2html and man, takes all of the man page filenames in a single command line and process them (if possible)? So it would just need to be:

man2html: ${MANPAGES} man2html.sh
        -./man2html.sh ${MANPAGES}

The man2html.sh tool could exit non-zero on error, which the make man2html would report but ignore.

Then you could add the man2html to part of make prep and make release.

The instead of using .gitignore to ignore the foo.html files, they could be added a files to the distribution AND then make release would regenerate them as needed.

[xexyl]

We looked at man2html v3.0.1 (also available on macOS via homebrew) ...

With commit 04df879

Added man2html rule

Because there is sometimes a more convenient ways to read documentation.

FWIW under CentOS:

$ rpm -q man2html
man2html-1.6-13.g.el7.x86_64

Fedora (36) has 1.6-29.g.fc36.

MacPorts does not have it. I can look at manually compiling it but that'll be another day. Going to shut the laptop down and get some sleep (though I'll be awake a while I fear).

I don't know if the options you added to the Makefile exist in older versions. I can have a look tomorrow and let you know. If so maybe you could add some way to test it. I'm not sure though: there doesn't seem to be an option that prints just the version.

In other words though this will not be a rule I can run most likely unless I can get it to compile under macOS another time. I'm sure I can if it's worth doing - but I'm not sure if it will be or not. Perhaps not since it won't need to be done very often I should think?

Anyway hope you have a great night. I have some things to commit tomorrow and maybe I'll have other things come up too. I'll also try getting to the comments above.

[xexyl]

We looked at man2html v3.0.1 (also available on macOS via homebrew) ...

With commit 04df879

Added man2html rule

Because there is sometimes a more convenient ways to read documentation.

UPDATE 0

We have a suggestion, @xexyl for you:

The make man2html rule is a tad bit long. Perhaps you should form a man2html.sh tool that checks for man2html and man, takes all of the man page filenames in a single command line and process them (if possible)? So it would just need to be:

man2html: ${MANPAGES} man2html.sh
        -./man2html.sh ${MANPAGES}

The man2html.sh tool could exit non-zero on error, which the make man2html would report but ignore.

Then you could add the man2html to part of make prep and make release.

The instead of using .gitignore to ignore the foo.html files, they could be added a files to the distribution AND then make release would regenerate them as needed.

See the comment I just posted. I can see if that's possible but it depends on what options are available and what you use. I'll look at it in the coming days.

Good night my friend!

EDIT: Possibly I could still write such a script even if the options are not available though. Will look at that in the coming days too. Anyway have a great night! Sleep well when you do.

EDIT 1: The man page for both CentOS and Fedora versions are dated 1998. Would you mind telling me what the authors are of the ones you have? I wonder if it's a different implementation? Or perhaps you can give the synopsis as well - or options? That way we can compare.

EDIT 2:

man2html(1)                                                     General Commands Manual                                                    man2html(1)

NAME
       man2html - format a manual page in html

SYNOPSIS
       man2html [options] [file]

DESCRIPTION
       man2html  converts a manual page as found in file (or stdin, in case no file argument, or the argument "-", is given) from man-style nroff into
       html, and prints the result on stdout.  It does support tbl but does not know about eqn.  The exit status is 0. If  something  goes  wrong,  an
       error page is printed on stdout.

       This  can  be  used  as  a  stand-alone utility, but is mainly intended as an auxiliary, to enable users to browse their man pages using a html
       browser like lynx(1), xmosaic(1) or netscape(1).

       The main part of man2html is the troff-to-html engine written by Richard Verhoeven (rcb5@win.tue.nl).  It adds  hyperlinks  for  the  following
       constructs:

       foo(3x)           "http://localhost/man/man2html?3x+foo"
       method://string   "method://string"
       www.host.name     "http://www.host.name"
       ftp.host.name     "ftp://ftp.host.name"
       name@host         "mailto:name@host"
       <string.h>        "file:/usr/include/string.h"

       (The first of these can be tuned by options - see below.)  No lookup is done - the links generated need not exist.  Also an index with internal
       hyperlinks to the various sections is generated, so that it is e

Netscape brings back memories! Okay so does lynx - but never mind that. :) Anyway I'll check into this tomorrow. Good night!

[xexyl]

Not left yet ... might have found it. Is it by Thomas Dickey? The one who is behind ncurses? Here's what I see in usage:

Usage: man2html [ options ] < infile > outfile
Options:
  -aliases <file>  : Filename containing mapping of aliases to actual manpages
  -bare            : Do not put in HTML, HEAD, BODY tags
  -belem <elem>    : HTML Element for overstruck text (def: "B")
  -botm <#>        : Number of lines for bottom margin (def: 7)
  -cgiurl <url>    : URL for linking to other manpages
  -cgiurlexp <url> : Perl expression URL for linking to other manpages
  -compress        : Compress consecutive blank lines
  -externs <file>  : Filename containing names to not link to
  -headmap <file>  : Filename of user section head map file
  -help            : This message
  -index           : Make an index of headers at the end
  -k               : Process a keyword search result
  -leftm <#>       : Character width of left margin (def: 0)
  -nodepage        : Do not remove pagination lines
  -noheads         : Turn off section head detection
  -pgsize <#>      : Number of lines in a page (def: 66)
  -seealso         : Link to other manpages only in the SEE ALSO section
  -solaris         : Process keyword search result in Solaris format
  -ssecm <#>       : Character width of subsection margin (def: 0)
  -sun             : Section heads are not overstruck in input
  -title <string>  : Title of manpage (def: Not defined)
  -toc             : Generate IDs compatible with HTML::Toc
  -topm <#>        : Number of lines for top margin (def: 7)
  -uelem <elem>    : HTML Element for underlined text (def: "I")

Description:
  man2html takes formatted manpages from STDIN and converts it to HTML sent
  to STDOUT.  The -topm and -botm arguments are the number of lines to the
  main body text and NOT to the running headers/footers.

Version:
  3.1
  Copyright 2001-2014,2015 Thomas E. Dickey
  Copyright (C) 1995-1997  Earl Hood, ehood@medusa.acs.uci.edu
  man2html comes with ABSOLUTELY NO WARRANTY and man2html may be copied only
  under the terms of the GNU General Public License, which may be found in
  the man2html distribution.

is this the right one? If so I'll look at making the script in the coming days. Going to sleep now. Good night!

UPDATE 0:

I see you actually included a link to it. But trying the link I can't seem to find a download to the tarball. Mind giving a direct link? Well past bedtime here. Good night!

[xexyl]

Just a quick comment:

If you react to comment #275 (comment) I will address the issues in the man pages you cited. I am also curious what you think of #275 (comment) and the man2html version issue as well. I believe that the one I linked will suffice but I want to be sure. Possibly check #275 (comment) too.

I hope to address comments #275 (comment) and #275 (comment) in the coming days. There are some other comments as well but those are not as important to the issue so I'm not as worried about them.

I'm really worn out today and I think I won't be doing anything else here today.

[lcn2]

We looked at man2html v3.0.1 (also available on macOS via homebrew) ...
With commit 04df879

Added man2html rule

Because there is sometimes a more convenient ways to read documentation.

UPDATE 0

We have a suggestion, @xexyl for you:
The make man2html rule is a tad bit long. Perhaps you should form a man2html.sh tool that checks for man2html and man, takes all of the man page filenames in a single command line and process them (if possible)? So it would just need to be:

man2html: ${MANPAGES} man2html.sh
        -./man2html.sh ${MANPAGES}

The man2html.sh tool could exit non-zero on error, which the make man2html would report but ignore.
Then you could add the man2html to part of make prep and make release.
The instead of using .gitignore to ignore the foo.html files, they could be added a files to the distribution AND then make release would regenerate them as needed.

See the comment I just posted. I can see if that's possible but it depends on what options are available and what you use. I'll look at it in the coming days.

Good night my friend!

EDIT: Possibly I could still write such a script even if the options are not available though. Will look at that in the coming days too. Anyway have a great night! Sleep well when you do.

EDIT 1: The man page for both CentOS and Fedora versions are dated 1998. Would you mind telling me what the authors are of the ones you have? I wonder if it's a different implementation? Or perhaps you can give the synopsis as well - or options? That way we can compare.

...

AUTHOR
       Earl Hood
       ehood@medusa.acs.uci.edu

ERRORS AND OMISSIONS
       Troff version of this document initially created for version 2.1.0 by C. Jeffery Small (jeff@cjsa.com) by copy-
       ing, reformatting, rearranging and partially rewriting the contents of the ascii text file doc/man2html.txt.

$ man2html -h
Option h is ambiguous (headmap, help)
Usage: man2html [ options ] < infile > outfile
Options:
  -bare            : Do not put in HTML, HEAD, BODY tags
  -belem <elem>    : HTML Element for overstriked text (def: "B")
  -botm <#>        : Number of lines for bottom margin (def: 7)
  -cgiurl <url>    : URL for linking to other manpages
  -cgiurlexp <url> : Perl expression URL for linking to other manpages
  -compress        : Compress consective blank lines
  -headmap <file>  : Filename of user section head map file
  -help            : This message
  -k               : Process a keyword search result
  -leftm <#>       : Character width of left margin (def: 0)
  -nodepage        : Do not remove pagination lines
  -noheads         : Turn off section head detection
  -pgsize <#>      : Number of lines in a page (def: 66)
  -seealso         : Link to other manpages only in the SEE ALSO section
  -solaris         : Process keyword search result in Solaris format
  -sun             : Section heads are not overstriked in input
  -title <string>  : Title of manpage (def: Not defined)
  -topm <#>        : Number of lines for top margin (def: 7)
  -uelem <elem>    : HTML Element for underlined text (def: "I")

Description:
  man2html takes formatted manpages from STDIN and converts it to HTML sent
  to STDOUT.  The -topm and -botm arguments are the number of lines to the
  main body text and NOT to the running headers/footers.

Version:
  3.0.1
  Copyright (C) 1995-1997  Earl Hood, ehood@medusa.acs.uci.edu
  man2html comes with ABSOLUTELY NO WARRANTY and man2html may be copied only
  under the terms of the GNU General Public License, which may be found in
  the man2html distribution.

We recommend using HomeBrew for man2html:

$ brew install man2html

or compile via nonGNU man2html page.

[xexyl]

What other man page tasks need to be done .. or is this issue ready to be closed?

The json semantics tables related tools - which I'm not so clear on them.

Same with dyn_array man page.

I think those are the only ones left?

[lcn2]

What other man page tasks need to be done .. or is this issue ready to be closed?

The json semantics tables related tools - which I'm not so clear on them.

Same with dyn_array man page.

I think those are the only ones left?

Yes you are correct.

[xexyl]

What other man page tasks need to be done .. or is this issue ready to be closed?

The json semantics tables related tools - which I'm not so clear on them.
Same with dyn_array man page.
I think those are the only ones left?

Yes you are correct.

Maybe we're finally getting to the point of being able to invite more public feedback. I hope so.

[lcn2]

What other man page tasks need to be done .. or is this issue ready to be closed?

The json semantics tables related tools - which I'm not so clear on them.
Same with dyn_array man page.
I think those are the only ones left?

Yes you are correct.

Maybe we're finally getting to the point of being able to invite more public feedback. I hope so.

Issue #87 documents our good progress!

[xexyl]

What other man page tasks need to be done .. or is this issue ready to be closed?

The json semantics tables related tools - which I'm not so clear on them.
Same with dyn_array man page.
I think those are the only ones left?

Yes you are correct.

Maybe we're finally getting to the point of being able to invite more public feedback. I hope so.

Issue #87 documents our good progress!

True and it looks great! As for that see comment #87 (comment) there.

[xexyl]

Are the comments

#275 (comment)

#275 (comment)

still relevant?

The second one about man2html script is maybe less important since it doesn't even seem to work right (man2html itself) but the other one might be relevant? What do you think?

--

I don't think I'll be doing anything else (other than the commits I did earlier today) today. I am aware of some issues with some of the markdown in some of my winning entries but I'm not sure exactly how you have it all set up yet so I've not committed them. I do believe I have another pull request open on that repo though. I'm waiting on more information on the way the website will be generated etc. before I worry about the fixes to my entries. I should maybe open an issue on the winner repo but for now I'm going to do something else - for the rest of the day.

Have a great day!

[xexyl]

With commit ade28d2 there is now a man page for dyn_array and with commit a215112 it now has a README file (named here dyn_array.md). However do please note that I'm at loss on part of it since it currently uses the dbg facility as well. Thus although it's been written some things should be updated in it. I'll do that once that's been discussed and resolved. As I think it has more relevancy in the thread about reducing top directory clutter I'll also say this there.

[lcn2]

Are the comments

#275 (comment)

#275 (comment)

still relevant?

comment 1179412882 does not seem relevant.

Regarding comment 1179439529:

The second one about man2html script is maybe less important since it doesn't even seem to work right (man2html itself) but the other one might be relevant? What do you think?

We agree.

Should we simply abandon the HTML pages OR can you find a better replacement OR ???

[xexyl]

Are the comments
#275 (comment)
#275 (comment)
still relevant?

comment 1179412882 does not seem relevant.

Thank you.

Regarding comment 1179439529:

The second one about man2html script is maybe less important since it doesn't even seem to work right (man2html itself) but the other one might be relevant? What do you think?

We agree.

Should we simply abandon the HTML pages OR can you find a better replacement OR ???

I do have a link here that has some other options but if none of these work then maybe we should abandon it. I'm not sure I'll look into it today but it's something that maybe we should do. I'm almost ready to commit the other changes. Just running some tests to make sure it goes okay. Seems fine though.

[xexyl]

https://invisible-island.net/scripts/man2html.html is a good discussion with a list of a number of tools. He also linked to a SE post with the question and some others have some suggestions of different kinds. Whether the latter is of any use I don't know.

[xexyl]

With commit ab97007 we have the (I believe) last remaining man pages added.

See the log please as I need to leave for now. It might or might not be that these man pages can be improved - I note some example ways (including examples) in the log.

I don't expect to do anything else today but I feel good about this. Are we good to close this or should we keep it open until I have gone through consistency (and formatting) and also deciding the man2html issue ?

Personally I like to keep it open until everything is resolved but if you think we can close this and want to (both) go ahead. Or else I can. But I do warn again that these man pages could be improved.

Good day!

[lcn2]

Perhaps we should simply abandon forming the HTML pages from the man pages, @xexyl ?

[xexyl]

Perhaps we should simply abandon forming the HTML pages from the man pages, @xexyl ?

That sounds reasonable to me yes.

So I have to fix those two or three man pages but otherwise this issue is resolved unless some other tool comes up.

However there’s one thing to consider. I still need to go over them all to make everything consistent and check for typos etc. When do you think I should do that? My thinking is I should wait until we’re absolutely positive that nothing else needs to be written or changed in the man pages (or more specifically until after everything written is complete).

Do you think that we should do that after I fix those man pages or should we wait a bit longer?

[lcn2]

Perhaps we should simply abandon forming the HTML pages from the man pages, @xexyl ?

That sounds reasonable to me yes.

So I have to fix those two or three man pages but otherwise this issue is resolved unless some other tool comes up.

However there’s one thing to consider. I still need to go over them all to make everything consistent and check for typos etc. When do you think I should do that? My thinking is I should wait until we’re absolutely positive that nothing else needs to be written or changed in the man pages (or more specifically until after everything written is complete).

Do you think that we should do that after I fox those man pages or should we wait a bit longer?

Yes, that sounds very reasonable.

[xexyl]

Perhaps we should simply abandon forming the HTML pages from the man pages, @xexyl ?

That sounds reasonable to me yes.
So I have to fix those two or three man pages but otherwise this issue is resolved unless some other tool comes up.
However there’s one thing to consider. I still need to go over them all to make everything consistent and check for typos etc. When do you think I should do that? My thinking is I should wait until we’re absolutely positive that nothing else needs to be written or changed in the man pages (or more specifically until after everything written is complete).
Do you think that we should do that after I fox those man pages or should we wait a bit longer?

Yes, that sounds very reasonable.

I hope that I was typing that on my phone!

Anyway: which way do you think it should be? Once those man pages are fixed I should go ahead and make everything consistent or should I wait until later?

I hope to get to the other comment later on today. Trying to solve an issue completely unrelated.

[xexyl]

Some thoughts on this issue crossed my mind. One of them I already thought of before (much earlier on) but did not bring up. That's the first one (or is that first 0 ? :) )

0. Should we have a man page (with the .so ... to link to dbg.3/dyn_array.3) for each of the dbg() and dyn_array functions?

1. Should we have a jparse.3 man page for the library? I mean it's fine and well to have the jparse tool itself documented (as in jparse.1) but probably most people would use it as a library so shouldn't it have a man page for section 3? If so should it also be done like I have in the first item in this list?

2. As far as consistency with man pages: once we're sure that we have no other tools that have to be added and no other man pages have to be added (see item 1 above but others maybe also?) as well as we know that the content is correct (the json semantics tables ones are not completely correct) - then I can go through them all and make it so that everything is consistent.

[lcn2]

Some thoughts on this issue crossed my mind. One of them I already thought of before (much earlier on) but did not bring up. That's the first one (or is that first 0 ? :) )

0. Should we have a man page (with the .so ... to link to dbg.3/dyn_array.3) for each of the dbg() and dyn_array functions?

Yes.

1. Should we have a jparse.3 man page for the library? I mean it's fine and well to have the jparse tool itself documented (as in jparse.1) but probably most people would use it as a library so shouldn't it have a man page for section 3? If so should it also be done like I have in the first item in this list?

Yes and Yes.

2. As far as consistency with man pages: once we're sure that we have no other tools that have to be added and no other man pages have to be added (see item 1 above but others maybe also?) as well as we know that the content is correct (the json semantics tables ones are not completely correct) - then I can go through them all and make it so that everything is consistent.

Yes, that is a good idea, @xexyl

[xexyl]

Some thoughts on this issue crossed my mind. One of them I already thought of before (much earlier on) but did not bring up. That's the first one (or is that first 0 ? :) )

0. Should we have a man page (with the .so ... to link to dbg.3/dyn_array.3) for each of the dbg() and dyn_array functions?

Yes.

1. Should we have a jparse.3 man page for the library? I mean it's fine and well to have the jparse tool itself documented (as in jparse.1) but probably most people would use it as a library so shouldn't it have a man page for section 3? If so should it also be done like I have in the first item in this list?

Yes and Yes.

2. As far as consistency with man pages: once we're sure that we have no other tools that have to be added and no other man pages have to be added (see item 1 above but others maybe also?) as well as we know that the content is correct (the json semantics tables ones are not completely correct) - then I can go through them all and make it so that everything is consistent.

Yes, that is a good idea, @xexyl

Thanks. This gives me some things to do. I also don’t know how my week will go but I hopefully will be able to at least start this soon.

[xexyl]

Okay as for the jparse.3: what functions should be included? That needs to be decided before I can do that.

As for the dyn_array.3 and dbg.3 that's easy enough but I need to figure out how to break the functions up. For dbg.3 it's easier because there already are sections but for the other one maybe not as clear. This will take some time and effort and as I noted elsewhere I'm not having a good day. I don't think I'll be up to working on this unfortunately at least today. Hopefully tomorrow will be better.

UPDATE 0

Obviously these have to be documented:

/*
 * function prototypes for jparse.l
 */
extern struct json *parse_json(char const *ptr, size_t len, char const *filename, bool *is_valid);
extern struct json *parse_json_stream(FILE *stream, char const *filename, bool *is_valid);
extern struct json *parse_json_file(char const *name, bool *is_valid);

but what other ones?

UPDATE 1

Obviously these too:

extern bool json_dbg_allowed(int json_dbg_lvl);
extern bool json_warn_allowed(void);
extern bool json_err_allowed(void);
extern void json_dbg(int json_dbg_lvl, char const *name, const char *fmt, ...) \
        __attribute__((format(printf, 3, 4)));          /* 3=format 4=params */
extern void json_vdbg(int json_dbg_lvl, char const *name, const char *fmt, va_list ap);

What about the rest in that file - json_util.h ? Some of them seem like good candidates but I don't know if they're all needed. Some of them might take some time and thought in documenting and that goes for this file as well as others.

Any others ?

[xexyl]

Another thing. The dyn_array facility needs an example program. So far I have not done this because it still uses the debug facility - another repo. What do you have in mind for resolving this situation? We could realistically just use a simpler version of dyn_test.c but even so the fact it uses dbg.h might be a problem for when it's its own repo.

Doing something else now. I was really hoping to work on the man page thing today but I don't see that happening.

[lcn2]

Okay as for the jparse.3: what functions should be included? That needs to be decided before I can do that.

As for the dyn_array.3 and dbg.3 that's easy enough but I need to figure out how to break the functions up. For dbg.3 it's easier because there already are sections but for the other one maybe not as clear. This will take some time and effort and as I noted elsewhere I'm not having a good day. I don't think I'll be up to working on this unfortunately at least today. Hopefully tomorrow will be better.

UPDATE 0

Obviously these have to be documented:

/*
 * function prototypes for jparse.l
 */
extern struct json *parse_json(char const *ptr, size_t len, char const *filename, bool *is_valid);
extern struct json *parse_json_stream(FILE *stream, char const *filename, bool *is_valid);
extern struct json *parse_json_file(char const *name, bool *is_valid);

but what other ones?

UPDATE 1

Obviously these too:

extern bool json_dbg_allowed(int json_dbg_lvl);
extern bool json_warn_allowed(void);
extern bool json_err_allowed(void);
extern void json_dbg(int json_dbg_lvl, char const *name, const char *fmt, ...) \
        __attribute__((format(printf, 3, 4)));          /* 3=format 4=params */
extern void json_vdbg(int json_dbg_lvl, char const *name, const char *fmt, va_list ap);

What about the rest in that file - json_util.h ? Some of them seem like good candidates but I don't know if they're all needed. Some of them might take some time and thought in documenting and that goes for this file as well as others.

Any others ?

We think the functions above are the most important to document, plus:

#define JPARSE_VERSION ...

BTW: the dog(3) and dyn_alloc(3) man pages should document their #define version strings too.

We don't need every version string documented, the commands with -V do that already. It is just the programmatic interfaces that should document their #define version strings.

By document, @xexyl, we do NOT mean document the actual value. We don't want to have to update the man page every time there is a version string. Instead you can document the general format of the version string and give an example value. When you do, mention that the example value is just an example for illustrative purposes and will have from release to release.

[lcn2]

Another thing. The dyn_array facility needs an example program. So far I have not done this because it still uses the debug facility - another repo. What do you have in mind for resolving this situation? We could realistically just use a simpler version of dyn_test.c but even so the fact it uses dbg.h might be a problem for when it's its own repo.

Doing something else now. I was really hoping to work on the man page thing today but I don't see that happening.

Good idea.

The dyn_array/dyn_test.c is the example program. For the man page you can put the core code from the main function if you wish to include an example in the man page, @xexyl.

[xexyl]

Another thing. The dyn_array facility needs an example program. So far I have not done this because it still uses the debug facility - another repo. What do you have in mind for resolving this situation? We could realistically just use a simpler version of dyn_test.c but even so the fact it uses dbg.h might be a problem for when it's its own repo.
Doing something else now. I was really hoping to work on the man page thing today but I don't see that happening.

Good idea.

The dyn_array/dyn_test.c is the example program. For the man page you can put the core code from the main function if you wish to include an example in the man page, @xexyl.

I was thinking something like that yes. Not sure what I'll get done today but hopefully I can do at least one thing if not more. Hope you're having a nice sleep!

[xexyl]

Okay as for the jparse.3: what functions should be included? That needs to be decided before I can do that.
As for the dyn_array.3 and dbg.3 that's easy enough but I need to figure out how to break the functions up. For dbg.3 it's easier because there already are sections but for the other one maybe not as clear. This will take some time and effort and as I noted elsewhere I'm not having a good day. I don't think I'll be up to working on this unfortunately at least today. Hopefully tomorrow will be better.

UPDATE 0

Obviously these have to be documented:

/*
 * function prototypes for jparse.l
 */
extern struct json *parse_json(char const *ptr, size_t len, char const *filename, bool *is_valid);
extern struct json *parse_json_stream(FILE *stream, char const *filename, bool *is_valid);
extern struct json *parse_json_file(char const *name, bool *is_valid);

but what other ones?

UPDATE 1

Obviously these too:

extern bool json_dbg_allowed(int json_dbg_lvl);
extern bool json_warn_allowed(void);
extern bool json_err_allowed(void);
extern void json_dbg(int json_dbg_lvl, char const *name, const char *fmt, ...) \
        __attribute__((format(printf, 3, 4)));          /* 3=format 4=params */
extern void json_vdbg(int json_dbg_lvl, char const *name, const char *fmt, va_list ap);

What about the rest in that file - json_util.h ? Some of them seem like good candidates but I don't know if they're all needed. Some of them might take some time and thought in documenting and that goes for this file as well as others.
Any others ?

We think the functions above are the most important to document, plus:

#define JPARSE_VERSION ...

Thank you. Can you think of any other function that might be of use? Well maybe I'll see something when I get to it.

BTW: the dog(3) and dyn_alloc(3) man pages should document their #define version strings too.

What about cat(1) ? :)

We don't need every version string documented, the commands with -V do that already. It is just the programmatic interfaces that should document their #define version strings.

Right.

By document, @xexyl, we do NOT mean document the actual value. We don't want to have to update the man page every time there is a version string. Instead you can document the general format of the version string and give an example value. When you do, mention that the example value is just an example for illustrative purposes and will have from release to release.

Good for clarification as I was not sure about that - and the concern you had also crossed my mind.

[xexyl]

Another thing. The dyn_array facility needs an example program. So far I have not done this because it still uses the debug facility - another repo. What do you have in mind for resolving this situation? We could realistically just use a simpler version of dyn_test.c but even so the fact it uses dbg.h might be a problem for when it's its own repo.
Doing something else now. I was really hoping to work on the man page thing today but I don't see that happening.

Good idea.
The dyn_array/dyn_test.c is the example program. For the man page you can put the core code from the main function if you wish to include an example in the man page, @xexyl.

I was thinking something like that yes. Not sure what I'll get done today but hopefully I can do at least one thing if not more. Hope you're having a nice sleep!

Actually this won't work right because dyn_array.h includes ../dbg/dbg.h and this means that when it's its own repo where will dbg come from? It would be fine the example file only included its own header file but obviously it has to include dyn_array.h also.

What do you propose?

[xexyl]

Okay as far as the man page splitting up there's more than one way to go about it I'm realising. I'm not up to actually doing any of them right now but I can at least discuss the ideas.

Method 0

Copy the dbg.3 file to individual files (with the name of the function) but make it in a temporary directory (so I can use sed to replace everything needed quickly). Instead of having one main file for each group (info, warn, debug etc.) I could have them all links to the main dbg.3 which has everything. This seems less clean but it's easier and quicker to do I imagine.

Method 1

I could instead have as I noted above a main man page for each category (info, warn, debug etc.) and then have the remaining functions (in that category) link to the main man page (of that category).

Method 2 ?

There probably are other ways and one would be to start out like 0 and then move to 1 in time.

Other points

If I choose 1 then I have to change dbg.3 quite a bit but I can yank paste (or delete paste) a lot of text. If I do not choose 1 I will have to do less work and less to dbg.3 itself. If I don't link to dbg.3 in all of them then there will have to be other changes to dbg.3 also. If it's all in dbg.3 then it will require less work in the other man pages as well. It'll be fewer number of links too (one link but in all files).

Now the question is which way to go. That's a good question. What of it?

Using the quicker way might be ideal in some ways as it lets us worry about other things (including that elusive thing called 'real life' which after all these years on the planet I've yet to determine if it's a myth or not). But it's not as useful to the user maybe. The quicker way is of course easier too.

What do I do? I don't know. What would you prefer? My guess is it's the way I would prefer too but will take more time and thought - the way of breaking it up. I know what man pages I can use as a model too: those for curses. But it'll take some work. I'm not up to that work today at least.

I think that once I have dbg.3 set up I can kind of adapt it for dyn_array.3 and also the to be written jparse.3 man page as well. Maybe doing dyn_array.3 first would be easier as there are fewer functions but the categories are less clear to me there as well.

I'm going to do other things for the rest of the day but if you reply and I'm able to do I'll get back to writing here. It might be that I need to wait until after the holiday - and some days later as there will be quite a lot of stimulation that day which always exhausts me even more than usual. But perhaps I'll be able to start out on it before then. If so that would be tomorrow but I doubt it honestly (even though I'd like to get it done).

I am sleeping a bit more but not good sleep either (never is). Whether the more sleep will last or not I don't know but I hope so. Even so I'm not any more rested than I had been and I've been feeling low for some time now as well (and for reasons I've yet to figure out if it's other t has the trying to fix the sleep schedule which is of course necessary).

Hope you're having a great day and wishing you a great holiday and new year (I have a meme to share with you at that time though)!

[xexyl]

Making really good progress on this issue but I need to take a break to do some other things!

I should be able to finish it today. I'm at the place where I need to finally modify dbg.3 and then create all the files that link to the appropriate man pages.

I'll be probably an hour before I can do anything more - at the least.

[xexyl]

Making really good progress on this issue but I need to take a break to do some other things!

I should be able to finish it today. I'm at the place where I need to finally modify dbg.3 and then create all the files that link to the appropriate man pages.

I'll be probably an hour before I can do anything more - at the least.

See #444 (comment) and in particular some discussion things to consider. In particular:

Also because a lot of man pages have been added aside from these I moved
the man pages to man/man3 (like in an installed system).

A note is that there is room for improvement here. This is a work in
progress but enough work has been done to commit.

An important point is that although the Makefile now installs those man
pages it does not install the man pages for the additional man pages
with the .so man3/foo.3 in it. This is because there are a lot of them
and the way to go about it might be up to discussion first. There even
are some other ideas as opposed to using .so.

Another method might be to use symlinks so that one can do

     man ./man/man3/werr.3

for example and get the man page output whereas this will not happen if
it's not installed. Another option is to have make install use ln to
make symlinks. The way it currently stands is that one can only do:

    man man/man3/err.3
    man man/man3/warn.3
    man man/man3/werr.3
    man man/man3/warn_or_err.3
    man man/man3/printf_usage.3
    man man/man3/msg.3

and expect the right output as each one will have the group of
functions. But whether we want to make it symlinks instead - that might
be an idea. Depending on what is decided will change how make install
works.

Note that only the main man pages are installed. I'm not sure what we want for the rest so I've left that off. Well another reason is I don't feel up to doing any more today but I think it's something that has to be decided anyway.