-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Discuss documentation #1
Comments
I also just noticed something with the example program I wrote. Perhaps it should tell the user what is going to happen before it happens as it might be alarming to some people to run it and see errors and warnings. Currently one would see: $ ./dbg_example
Warning: main: elephant is sky-blue pink
debug[3]: file: foo.bar has length: 7
ERROR[2]: main: test: errno[1]: Operation not permitted but perhaps it should at least say something before each example function is used (what will be called and with the same args and also what the output should look like - kind of like I have in the comments)? What do you think? |
With commit 09b6563e8f38213eceafc01e9a1ca80458c2987c there are 6 new functions in the dbg facility:
extern void snmsg(char *str, size_t size, char const *fmt, ...)
extern void sndbg(char *str, size_t size, int level, char const *fmt, ...);
extern void snwarn(char *str, size_t size, char const *name, char const *fmt, ...);
extern void snwarnp(char *str, size_t size, char const *name, char const *fmt, ...);
extern void snwerr(int error_code, char *str, size_t size, char const *name, char const *fmt, ...);
extern void snwerrp(int error_code, char *str, size_t size, char const *name, char const *fmt, ...);
These 6 new functions need to be documented. |
That is a good idea. |
I was thinking the same. At first I was thinking of the man page but now that I've read the full comment (I read preview in iOS mail notifications) I remembered the readme file as well. This brings up two points. First of all do you want to write those details in? Second of all whether you want to do that or not we should discuss the things I brought up (maybe in the other thread - not sure if it was this one or not and I'm not looking up .. just quickly replying to comments and then I hope to rest again: been awake since just after 0000 :( . I can elaborate more later if you need. Should I do that? |
Agreed. I just have to (0) find the energy and (1) figure out what to write before and after each test case. I will then have to update the man page as well (I am saying this so I do don't forget to do this). Hope you're having a nice sleep my friend! Would you do me a favour please? If I don't do the updates in the coming days please remind me. I hope I can do it before my surgery but if not I should not too many days after I should expect. |
We are not sure which details. Do you mean text for the 6 new functions? And by "write those details in" do you mean in a new comment in the thread, or write them elsewhere? |
Please elaborate more. |
Well I was thinking I'll have to elaborate on the other comment later on. Hope I can do it today but it might have to be another day. Have to go do the Covid test for the surgery on Thursday. Later I have another appointment. If I don't get to this today I hope you enjoy the rest of your day! |
This is one of the things I was thinking of though. Anyway I must get going. |
Again, very best wishes on your surgery prep, surgery experience, post surgery wake-up, and the long surgery recovery. Hope you find ways to make the experience enjoyable. If coding, code editing, code reviewing (all that you do for this repo etc.) helps before surgery,and when you find the energy after your surgery to work on this repo: please do. However, please try not to overdo it, especially avoid the point where it negatively impacts your recovery. We will be extra patient with a slower speed of your repo activity. We will welcome reading any OT general recovery progress updates after the surgeon edits you. 😷 We DO request you resist the urge to code during surgery. 😁 |
OK, we will. |
Thank you! Well someone dear to me got back in touch with me a few weeks ago so things are going well in a way. Picked up like it was yesterday. The true sign of a true friendship.
I really appreciate that! I won’t overdo it but I appreciate the reminder!
Thank you very much my friend! Funny way of putting it too!
Very funny! I assure you that I won’t! When I am allowed to I have twilight instead of general anaesthesia. If I am allowed and it’s something that will work for me I stay wide awake. This surgery requires general anaesthesia so I certainly won’t be working on the repo at the time 😀 It’s at 1330 and I probably will not be home until at least 1700 (at least!) hours and I will be going to sleep at that point. Of course I will have to get up because of my prostate but that’s always the case. I don’t know if I will say anything in the other thread until the next day but we’ll see. Hope you have a great day my friend! |
FYI: I have some updates to I was thinking I would commit them at the other repo and you could copy them over. However since I already forked this repo I might do it on both. If however I haven't done a pull request yet on either and you have a preference that I do it on one or the other please let me know. Hope you're having a nice sleep my friend! I'm going to try resting again. Hope you have a great day when you wake up! EDIT 0:This is what the changes make it look like: NOTE: Setting verbosity_level to DBG_MED: 3
NOTE: The next line should say: "Warning: main: elephant is sky-blue pink"
Warning: main: elephant is sky-blue pink
NOTE: The next line should read: "debug[3]: file: foo.bar has length: 7"
debug[3]: file: foo.bar has length: 7
NOTE: The next line should read: "ERROR[2]: main: test: errno[1]: Operation not permitted"
ERROR[2]: main: test: errno[1]: Operation not permitted The strings and errno values (including errno string) are specified via format specifiers so if for some reason there are different values they should still be correct on the same system. And with that I'm gone for a while - maybe for the day but we'll see - so I bid you well for now! |
With commit 4e229bc
We hope this will be enough for you, @xexyl , to complete the documentation of the new functions. |
I'll have a look in the coming days. We still have to somehow shrink down the file a lot as well. I think that discussion will help there somewhat but again not today. I'm just taking it easy a bit longer and then going to try and sleep. I would be going to sleep early tomorrow too but I have a zoom meeting so I might not be able to. Thursday we can assume I won't be doing anything but hopefully tomorrow I can get the example file committed. Hope you have a good rest of your day my friend! |
Somewhat OT:
I'm sure you gathered it already but I won't be doing anything today either. I'm very very tired. I have prepared a bit for surgery tomorrow though there are still a few things I need to do before I go to bed. I won't be doing anything tomorrow almost certainly. I will be leaving late morning but I have other things to do tomorrow prior to the surgery too (including a pre-op thing). I'll go to sleep when I get home. Friday I will be taking it easy most likely but we'll see what I manage in the coming days. Anyway I wanted to let you know and wish you a good rest of your day. |
OT: mental distractions in the hospitalBest wishes on being edited by the surgeon. Let's hope the surgeon prefers Suggestion: when you are in that twilight phase of post-op surgery recovery, think about a problem to solve entirely in your mind (no paper, no internet: nothing but your thoughts). Make sure this problem can take many hours to solve, or a problem that is open-ended: something that require you to hyper-focus on the problem instead of your post-surgery situation and all of those annoying machines that go bing and the many hospital bed interruptions of rest as the nursing staff does their work. Anyway, we selected a number theory problem to work on:
|
Thank you for the laugh - and quite a laugh it was! Just looking at it again I laughed out loud again.
I'm actually quite okay with that. I'm rather used to it. But then my first surgery I was 17 months old and back then the anaesthesia was worse - had that awful aftertaste. I have had more surgeries than most people could imagine ever having in many lifetimes! But soon as I wake up enough I'll be going home. When I'm home I'll go to sleep. However this problem you suggest is very intriguing and I'll have to look at it when I'm more awake. For now I am getting a snack before I sleep. Hope you have a great night my friend! I'll let you know how surgery goes when I can.
I like this! But at the same time it is a problem for someone like me.
Similar to above. This can be so annoying but at the same time I know what you mean.
Though I should say that although I do love numbers when I was in school I was not well and so I didn't do the best in maths. I have however surprised myself quite a lot with programming in what I have done maths wise. Back in 2017 during a talk with someone about something else entirely I figured out a way (and by during a talk I meant I was physically speaking!) to sum up powers of two. It's quite easy actually. What I mean is 1 + 2 + 4 + 8 + N. I need to get ready to sleep though so I'll pose this as a question: how would you go about it? Can you figure it out or do you already know even? I'll tell you my answer later on. Good night and thank you for the laugh and also suggestions! It might be something I look into. I do have some new films to watch too of course. Take good care for now and BCNU :) |
Hmm... for some reason setting up ssh key for this repo is not working right. I was hoping to set it up so I could do a pull request. I'm not sure if I will today for given reasons (and I want to go back to sleep in a bit but can't sleep for now) but I was hoping to at least set this up. Will possibly have to do this another time then and that might very well mean another day. I'll answer the accumulation (not accumulation: I can't think of the right word .. it's something like that I think but I'm too tired to ponder it more) of powers of two another time as well. Good day (though I know it's early morning)! |
I have a commit for this on the other repo but unfortunately there's a problem with my local copy. It happened a while back where a commit from another day (yesterday in this case) is there as well - as in it will be committed again. I don't know why this happens. I will have to possibly recreate my fork as that seems to be the solution. Maybe I can find another solution but if so that's not now. However I will have to defer this till later as after the surgery I have quite a bit of discomfort and pain (right now discomfort). However the files changed were Hope you're having a nice sleep my friend and good day to you! |
Can this issue be closed now ? Feel free to do so if you think it can be. |
Almost certainly yes .. once we get around to accessing a real computer and keyboard (not some hand held device) AND import the files from the mkiocccentry repo into this dbg repo. Until this happens, this issue should remain open .. but think of this as a reminder to us to import the files and close this issue when we do. |
What files have to be imported out of curiosity ? If it's the
Sure. And thank you again for the best wishes of my surgery and giving me an idea of something to do when waking up after it (see comment #1 (comment)). It was funny how you put the surgery and funny in general - a much needed laugh (or laughs)! |
Updates from the mkiocccentry repo have not been copied into the dbg repo for example, as this is not a high IOCCC priority. It is too bad that there isn't some form of "include file curds form repo URL whey" in
So probably it is best to not wish for a such a "include a file from an other repo" after all. We will just have to manually copy over code and documentation as we do now. |
You are most welcome. And don't forget to review your personal man page after being edited .. to be sure your own internal documentation remains up to date. 😀 |
Yes makes sense. What feature of git do you refer to though ? |
Very funny! Good word play in there too whether intentional or not. I'm still not in the clear of recovery. I mean the doctor was okay with me not going back but I'm having some issues (minor and he's not too concerned but given how awful the situation was I am being extra extra careful) and so I will be seeing him again. Hoping I won't have to go back many more times though. Well I'm off to do something else that doesn't require any thinking. Good day and good luck with Internet access / other things you mentioned! |
There isn't such a feature. |
Ah .. I thought when you referred to |
Updated the dbg repo as per the |
Great. |
As you requested on the
mkiocccentry
repo I am opening this here.To start out: what do you think should be changed with the man page? If you think it's complete for now how would you like it to be referred to in the README?
Looking at the repo I think it would be good if the README could be dramatically cut in size. I don't know what most people would prefer but I think some might look at the length (even with the
tl;dr
part) and look for something else instead. But perhaps with just thetl;dr
part referring to the man page (which actually has an example program) and another file that has more details (not sure what it would be called - maybe something to do with the api? I really don't know) it might seem much less formidable to some people?Just some initial thoughts to get a discussion started.
The text was updated successfully, but these errors were encountered: