Minetest logo

IRC log for #minetest-docs, 2022-01-03

| Channels | #minetest-docs index | Today | | Google Search | Plaintext

All times shown according to UTC.

Time Nick Message
00:14 MTDiscord <exe_virus> Okay, done driving for two days. On to the grocery... Looking around here you've all been busy bees
00:14 MTDiscord <Benrob0329> oh yes, lots has been done
00:15 MTDiscord <Benrob0329> I just "finished" the vector namespace PR (needs review and probably a couple revisions) and am about to start looking into the other PRs everyone else has opened
00:41 MTDiscord <josiah_wi> I don't have time today to review PRs, but tomorrow I'll check what I can review.
04:36 MTDiscord <Jonathon> whats the point of reviewing WIP/marked as draft PR's?
04:36 MTDiscord <Jonathon> obviously not complete
04:40 MTDiscord <Jonathon> also if the client and the server has the same api, do i need to duplicate the explanations, or just refer to above?
04:52 MTDiscord <Jonathon> well, duplicated for now
04:52 MTDiscord <Jonathon> is there a way to link a specific header in asciidoc if two have the same name?
05:00 MTDiscord joined #minetest-docs
08:46 MTDiscord <GreenXenith> I've opened a megatracker issue for progress on matching lua_api.txt coverage https://github.com/minetest/minetest_docs/issues/16
08:47 MTDiscord <GreenXenith> I tried to condense it using dropdowns but now if you tick a box the issue hangs for 2 seconds and the dropdown collapses, so I may have to get rid of the dropdowns
08:48 MTDiscord <GreenXenith> Also, there are significant issues with the voxelarea documentation, and I foresee snowballing problems if we don't address how to actually write the documentation.
08:50 MTDiscord <GreenXenith> Ive written a bunch of notes on it here https://gist.github.com/GreenXenith/3a269c5511fee3afd4fbe23517a1c94c; I would have used highlights but github doesnt support them, so I've bolded the problem areas and footnoted everything. This is both notes for @Luatic and the doc team in general, as this kind of stuff needs to be prevented later.
08:52 MTDiscord <GreenXenith> Essentially, we need a guide on what "good documentation" looks like, what kind of jargon to avoid, and when to use certain amounts of detail.
08:53 MTDiscord <GreenXenith> As it stands, it looks like the vmanip documentation was written by an experienced developer for an experienced developer
08:55 MTDiscord <GreenXenith> The project goals, policies, and documentation requirements need to be moved from the proposal to the readme as well.
09:00 MTDiscord <GreenXenith> And on the note of requirements, point 1 (ironically) needs to be clarified, point 2 needs explanation (somewhere) on how to show and explain examples, point 3 needs to be reworded to be about specific sections being linkable, and point 4 needs to be adjusted/clarified with something of the idea "easy enough to understand for a beginner, useful enough for a developer".
09:56 MTDiscord <j45> does anyone actually know what the colors property in the object properties table does/the wanted value for it?
10:56 MTDiscord <GreenXenith> It's probably to assign a solid color to uv groups to support meshes of the same style
10:57 MTDiscord <GreenXenith> let's see who git blames
10:59 MTDiscord <GreenXenith> wow, this is a 9 year old feature I didnt know existed until now
10:59 MTDiscord <GreenXenith> wasnt someone asking about this recently
10:59 MTDiscord <j45> :hypereyes:
11:00 MTDiscord <j45> according to fleck, color is multiplied with texture
11:00 MTDiscord <j45> so i would assume, as it is a table of colors, the first colour would be multiplied with the first texture, the second with the second... ect
11:00 MTDiscord <j45> cuz textures is also a table
11:01 MTDiscord <GreenXenith> time for science
11:10 MTDiscord <j45> https://github.com/minetest/minetest/blob/master/src/script/common/c_converter.cpp#L322-L339 it used this function so from this i assume it allows: {a = ,r = , g = , b =} (between 0 and 255) a number a string so i guess it is colorspec
11:11 MTDiscord <GreenXenith> I already assumed that
11:12 MTDiscord <j45> lol
11:13 MTDiscord <GreenXenith> Doesnt appear to be a functional feature
11:13 MTDiscord <luatic> GreenXenith: I feel basic terminology belongs somewhere else
11:13 MTDiscord <j45> reading the engine code isnt as bad as i imagined, as long as you are reading the right bit
11:13 MTDiscord <luatic> Not sprinkled everywhere
11:13 MTDiscord <GreenXenith> Gonna need more context than that
11:13 MTDiscord <luatic> https://gist.github.com/GreenXenith/3a269c5511fee3afd4fbe23517a1c94c
11:14 MTDiscord <GreenXenith> Still gonna need more context
11:14 MTDiscord <GreenXenith> I never said "include basic terminology", I said dont overload on useless information and technical jargon
11:14 MTDiscord <luatic> Programming-related terminology like "OOP" and "imperative" as well as MT-related terminology like "emerged"
11:14 MTDiscord <GreenXenith> Anyway, according to the original color commit (e42eeec): "New object property which allows changing the color and alpha of mesh materials. Due to the current lighting systems it doesn't work yet, but the full implementation is there"
11:14 MTDiscord <j45> should i ask in dev irc?
11:15 MTDiscord <j45> has it still not been fixed from 9 years ago? lol
11:15 MTDiscord <GreenXenith> I wouldnt be surprised
11:15 MTDiscord <GreenXenith> To be blunt, I dont really care what you as a developer think, I care what an inexperienced user thinks when they read this for the first time
11:16 MTDiscord <GreenXenith> (re: terminology)
11:16 MTDiscord <GreenXenith> And when an inexperienced user reads this, they are going to leave
11:16 MTDiscord <luatic> Feel free to rework it
11:16 MTDiscord <luatic> I will take your PR as an example as how to do it better next time :)
11:17 MTDiscord <GreenXenith> I called for discussion on standardization, not throwing myself at an issue that may recurr
11:17 MTDiscord <GreenXenith> Take your snark elsewhere
11:17 MTDiscord <luatic> That wasn't meant to be read in a snarky tone
11:17 MTDiscord <GreenXenith> Apologies then, I read it that way
11:18 MTDiscord <luatic> IMO you could even directly commit small fixes for readability improvements
11:19 MTDiscord <GreenXenith> re: 9 year old broken feature; Honestly, even if it were functional, if its only for color multiplication its useless with texture mods
11:19 MTDiscord <GreenXenith> So id hope you can use it without textures
11:19 MTDiscord <luatic> not exactly useless, texture mods have lots of downsides (such as filling up the cache)
11:20 MTDiscord <GreenXenith> re: fixing; I forgot to mention I excluded (most) grammatical notes since the main issues are with overall style and purpose
11:20 MTDiscord <GreenXenith> with a 9 year old feature, I wouldnt be surprised if it isnt hardware coloring and also fills up the cache
11:21 MTDiscord <GreenXenith> To cite the doc requirements, the current version is not accessible to all readers, regardless of skill level
11:23 MTDiscord <GreenXenith> The more pressing issue with the emerge thing is less "not knowing what it is", more not knowing where it came from since "emin" and "emax" dont exactly convey "emerged min" if you dont know what read_from_map returns
11:23 MTDiscord <luatic> cpp             // This allows setting per-material colors. However, until a real lighting             // system is added, the code below will have no effect. Once MineTest             // has directional lighting, it should work automatically.             if (!m_prop.colors.empty()) {                 m_spritenode->getMaterial(0).AmbientColor = m_prop.colors[0];                 m_spritenode->getMaterial(0).DiffuseColor =
11:23 MTDiscord m_prop.colors[0];                 m_spritenode->getMaterial(0).SpecularColor = m_prop.colors[0];             }
11:23 MTDiscord <GreenXenith> >directional lighting
11:23 MTDiscord <GreenXenith> >2012
11:23 MTDiscord <GreenXenith> color me impressed
11:23 MTDiscord <luatic> hehe
11:24 MTDiscord <GreenXenith> or dont, as the case may be
11:24 MTDiscord <luatic> but it never happened, did it?
11:24 MTDiscord <j45> so it doesnt work?? XD
11:24 MTDiscord <GreenXenith> Even if it did happen, how would they know the implementation would use those properties in particular?
11:24 MTDiscord <luatic> Wait lua             // Set mesh color (only if lighting is disabled)             if (!m_prop.colors.empty() && m_glow < 0)                 setMeshColor(mesh, m_prop.colors[0]);
11:25 MTDiscord <luatic> See if meshes can be colored
11:25 MTDiscord <GreenXenith> thats .. .what I tested on
11:25 MTDiscord <luatic> with a glow of 0?
11:25 MTDiscord <GreenXenith> is default glow not 0?
11:25 MTDiscord <j45> it is i think
11:25 MTDiscord <j45> yes, it is
11:26 MTDiscord <luatic> well, it wants a glow less than 0
11:26 MTDiscord <GreenXenith> ah, indeed
11:26 MTDiscord <j45> mt PR time?
11:27 MTDiscord <GreenXenith> glow of -1 still nothing, I would assume the engine maxes the values somewhere
11:27 MTDiscord <luatic> you can only get a glow < 0 at night
11:27 MTDiscord <luatic> or wait
11:27 MTDiscord <GreenXenith> fun fact: glow < 0 makes glow max
11:27 MTDiscord <j45> so it underflows?
11:28 MTDiscord <luatic> m_glow < 0 is impossible it seems
11:28 MTDiscord <luatic> ded code
11:30 MTDiscord <j45> gotta love this engine
11:31 MTDiscord <GreenXenith> (derp, glow < 0 disables lighting)
11:31 MTDiscord <luatic> and do the colors show then?
11:31 MTDiscord <luatic> because it's still very much possible that our shaders don't give a heck
11:32 MTDiscord <GreenXenith> > glow of -1 still nothing
11:32 MTDiscord <luatic> either way this "feature" is broken
11:32 MTDiscord <luatic> should document it as such
11:32 MTDiscord <GreenXenith> or .. just remove the documentation
11:32 MTDiscord <luatic> no
11:32 MTDiscord <GreenXenith> should probably open an issue to remove it, it never worked and therefore shouldnt be documented
11:33 MTDiscord <GreenXenith> its not even a deprecation
11:33 MTDiscord <luatic> it's a "caution" or "warning: don't use 'colors'" IMO
11:33 MTDiscord <j45> i will just add a warning saying that it doesnt work
11:34 MTDiscord <GreenXenith> "caution: dont use the foobar key because it doesnt do anything" is stupid
11:34 MTDiscord <luatic> because while the feature still "exists" (ie if they dump their props they will read "colors"), people will wonder why it's not documented by us
11:34 MTDiscord <luatic> it does do something, it even gets sent to the client
11:34 MTDiscord <luatic> you can set and get it
11:34 MTDiscord <GreenXenith> arent there other properties that get dumped that arent documented
11:34 MTDiscord <luatic> now I wonder whether you could use it for colorspec to colorstring
11:34 MTDiscord <j45> WARNING: This is feature is not functional.
11:34 MTDiscord <luatic> remove the first "is"
11:35 MTDiscord <j45> oh thanks
11:35 MTDiscord <luatic> are there?
11:35 MTDiscord <j45> i really need to start coffee-ing
11:35 MTDiscord <GreenXenith> I really need to sleep
11:35 MTDiscord <GreenXenith> its 3:30AM
11:35 MTDiscord <j45> go sleep than
11:35 MTDiscord <luatic> good night
11:35 MTDiscord <j45> gn
11:36 MTDiscord <GreenXenith> how the colors get documented doesnt really matter, what matters is we answered the original question: It does not work.
11:36 MTDiscord <j45> yes
11:37 MTDiscord <luatic> Fun fact: You could abuse the object properties to convert a colorspec into an ARGB8 "colortable": lua object:set_properties{colors = "green#08"} local colortable = object:get_properties().colors[1]
11:38 MTDiscord <GreenXenith> that is disgusting
11:39 MTDiscord <j45> ^
11:39 MTDiscord <luatic> I know. Don't worry, I wouldn't use this in my mods as I already have modlib.minetest.colorspec.
11:39 MTDiscord <exe_virus> Bedtime?*
11:39 MTDiscord <luatic> ||inb4 "that's disgusting too"||
11:40 MTDiscord <GreenXenith> good thing minetest.colorspec_to_bytes exists in 5.5
11:40 MTDiscord <j45> go sleep GX
11:40 MTDiscord <luatic> dad instincts?
11:40 MTDiscord <exe_virus> No, just genuine concern for anyone staying up what sounds like an extra 4 hours
11:40 MTDiscord <j45> ono this convo is gonna get out of hand
11:41 MTDiscord <GreenXenith> I woke up at noon, so ive only been up 9 hours. that doesnt mean im not tired though.
11:43 MTDiscord <GreenXenith> So yeah, goodnight. Ill see how much doc discussion I miss when I wake up ;p
11:44 MTDiscord <j45> gn!
11:53 MTDiscord <j45> i was just checking lua_api.txt and i noticed https://github.com/minetest/minetest/blob/master/doc/lua_api.txt#L7190 contradicts https://github.com/minetest/minetest/blob/master/doc/lua_api.txt#L7215
12:03 MTDiscord <j45> https://discord.com/channels/369122544273588224/747163566800633906/927532536962367538 btw
12:18 MTDiscord <j45> is there any point in having the approved column in the project board? after all, isnt one approval all we need?
12:30 appguru joined #minetest-docs
13:26 MTDiscord <Sublayer plank> ^ this
13:29 MTDiscord <Sublayer plank> I feel like we should try to make the documentation at least a bit easier for inexperienced users (which currently lua_api.txt sorta lacks)
13:30 MTDiscord <Sublayer plank> but at the same time, don't dumb it down too much
13:56 appguru joined #minetest-docs
15:04 MTDiscord <Benrob0329> We do need to make some doc writing guidelines, as well as organization, and user presentation.
15:05 MTDiscord <Benrob0329> I think that we should try to get the current PRs finished so that we have some material to work with
15:12 MTDiscord <j45> the only thing left for #12 is expanding on the wielditem value for the visual property
15:16 MTDiscord <luatic> Consider noting that it does support hardware colorization
15:17 MTDiscord <luatic> wield3d doesn't take advantage of this which means my colored brushes don't get shown properly >:(
15:17 MTDiscord <luatic> (and yes I have a WIP wield mod which does it properly)
15:18 MTDiscord <exe_virus> Second what Benrob says, we have enough pending info we could define the style and look and guides etc.
15:18 MTDiscord <luatic> https://github.com/minetest/minetest/blob/master/doc/lua_api.txt#L2174-L2176 <- these two are supported
15:25 ROllerozxa it's a bit irritating that asciidoc doesn't support separately aligning headers to the cells themselves
15:29 appguru joined #minetest-docs
15:37 MTDiscord <Benrob0329> Can you give an example?
15:48 ROllerozxa I want to left align a table column since it contains a sizable chunk of text, but this requires that column's header cell to be left aligned as well. There's an example for it in the PR I'm just about to open for my supported file formats page.
15:55 ROllerozxa oh, github's asciidoc preview automatically centers table headers... but asciidoctor-generated html doesn't for me
16:01 MTDiscord <Benrob0329> Try [.left]##Header##
16:02 MTDiscord <Benrob0329> 'scuse me, [.center]##Header##
16:02 MTDiscord <Benrob0329> With your header in place of Header
16:03 MTDiscord <Benrob0329> This kinda feels like an output style kind of thing though, not something we should set in the AsciiDoc
16:08 MTDiscord <Benrob0329> Oh wait, there's a thing to do this
16:09 MTDiscord <Benrob0329> https://docs.asciidoctor.org/asciidoc/latest/tables/format-cell-content/
16:11 MTDiscord <Benrob0329> Try prefixing a ^ to the cell
16:11 MTDiscord <Benrob0329> (Mean literally the ^ character)
16:11 ROllerozxa yep, that works, thanks!
16:51 MTDiscord <j45> the wielditem value?
16:51 MTDiscord <luatic> yes
16:52 MTDiscord <j45> should i do that in a TIP or a CAUTION?
16:53 MTDiscord <Benrob0329> Is this a helpful note, or a precautionary one?
16:53 MTDiscord <Benrob0329> Will things go wrong if they don't follow your advise?
16:53 MTDiscord <j45> they will waste time i guess
16:54 MTDiscord <josiah_wi> I'd say CAUTION then.
16:54 MTDiscord <luatic> TIP
16:55 MTDiscord <Benrob0329> Generally think if it like this: "TIP: It's easier if you do this.", "CAUTION: It won't work unless you do this.", "WARNING: This will be a security vulnerability or a crash if you don't do this."
16:57 MTDiscord <Benrob0329> I need to change a few WARNINGs to CAUTUONs in my PR actually, I had forgotten we have CAUTION until I saw it in Luatic's PR
16:57 MTDiscord <j45> @josiah_wi what do you mean here?
16:57 MTDiscord <j45> https://cdn.discordapp.com/attachments/926231483155378176/927606674188013618/unknown.png
16:58 MTDiscord <josiah_wi> Ah, I meant that the field type could be a link to another documentation page, or another documentation section.
16:58 MTDiscord <josiah_wi> Everywhere I put something_def I'm assuming it will be a link to more documentation.
16:59 MTDiscord <j45> should i comment that out or leave it there?
17:00 MTDiscord <josiah_wi> Hmm, it doesn't really belong on the page, so I'd say comment it out.
17:01 MTDiscord <luatic> ^
17:01 MTDiscord <luatic> This one is a tip which makes the user recall that meta controls an itemstacks appearance
17:18 MTDiscord <j45> :hypereyes:
17:18 MTDiscord <j45> https://cdn.discordapp.com/attachments/926231483155378176/927611972290232370/unknown.png
17:18 MTDiscord <j45> https://cdn.discordapp.com/attachments/926231483155378176/927611972520906803/unknown.png
17:20 MTDiscord <j45> i think #12 might be ready, can someone check?
17:24 MTDiscord <josiah_wi> Let me render it quick and make sure it all looks good.
17:24 MTDiscord <j45> sure
17:25 MTDiscord <josiah_wi> > Whether or not a model is backface culled.
17:25 MTDiscord <josiah_wi> Maybe modders normall know about this, but I happen to know about it just barely from seeing graphics discussions.
17:26 MTDiscord <josiah_wi> Since we're targeting an audience possibly including young modders etc. would a link to a definition, or some explanation be appropriate?
17:26 MTDiscord <josiah_wi> Lemme just put a review.
17:26 MTDiscord <j45> ok
17:35 MTDiscord <josiah_wi> j45, I highly recommend installing asciidoctor to preview stuff.
17:35 MTDiscord <josiah_wi> There are a couple places where you need a newline before a TIP etc. and this is easily noticed by looking at the HTML.
17:37 MTDiscord <josiah_wi> Review submitted.
17:38 MTDiscord <j45> i do have a previewer and it all seems to work
17:38 MTDiscord <j45> https://cdn.discordapp.com/attachments/926231483155378176/927617022332907530/unknown.png
17:38 MTDiscord <j45> https://cdn.discordapp.com/attachments/926231483155378176/927617022601359432/unknown.png
17:40 MTDiscord <josiah_wi> For HTML the newline before a TIP is necessary, as far as asciidoctor is concerned. 🥴
17:40 MTDiscord <josiah_wi> I marked the two places where I noticed it did not display correctly in my browser.
17:43 MTDiscord <Benrob0329> Generally if you use a technical term, either linking to further documentation or giving a brief explanation in parentheses is probably best.
17:44 MTDiscord <Benrob0329> > backface culled (the faces who's back is towards us aren't rendered).
17:44 MTDiscord <Benrob0329> For example.
17:46 MTDiscord <Benrob0329> Also @GreenXenith, so that you specifically see this too: The goal right now is (and has been) to rough in some docs and then agree on the good parts between them, and make everything more consistent.
17:46 MTDiscord <josiah_wi> Ah, I'll keep that in mind also.
17:46 MTDiscord <Benrob0329> So don't get too panicked that everything is a little haphazard right now.
17:47 MTDiscord <j45> Whether or not a model is backface culled (the faces who’s back is towards a player aren’t rendered). is this better?
17:47 MTDiscord <Benrob0329> I should probably make an issue or update the README with that info, but it didn't seem strictly necessary before.
17:47 MTDiscord <Benrob0329> @j45 Act like you're speaking to the reader
17:48 MTDiscord <j45> Whether or not the faces of a model that aren’t facing a player rendered.
17:49 MTDiscord <Benrob0329> You're getting more technical, not less
17:49 MTDiscord <j45> Whether bits of a model that a player cant see are loaded.
17:50 MTDiscord <Benrob0329> That's not always true though, and ignores transparent textures
17:51 MTDiscord <j45> maybe i should just link https://en.wikipedia.org/wiki/Back-face_culling
17:52 MTDiscord <Benrob0329> That seems like a horrible solution for what should have a brief explanation
17:53 MTDiscord <Benrob0329> "backface culled (the faces of the model who's back is towards you aren't shown)"
17:54 MTDiscord <Benrob0329> But then, if this is for the backface_culling option, why are you restating that it controls backface culling and not explaining what that means to begin with?
17:55 MTDiscord <Benrob0329> We need to avoid "the floor here is made out of floor" statements
17:59 MTDiscord <Benrob0329> Something like: asciidoc === `backface_culling`: `bool`  When `true`:: Faces who's back is towards the camera aren't rendered. Otherwise:: Faces are rendered no matter their orientation.
17:59 MTDiscord <j45> i have pushed my last commit for today as i need to go, and school starts again tmr but i hope to make some more progress after school if i can
17:59 MTDiscord <luatic> But then you have to go into detail about the normal-based definition of "backface"
17:59 MTDiscord <luatic> and normal recalculation...
18:00 MTDiscord <Benrob0329> We need to here?
18:00 MTDiscord <Jonathon> no
18:00 MTDiscord <Benrob0329> That seems like it deserves its own whole thing, this is just supposed to give a useful explanation of what this property does
18:01 MTDiscord <luatic> Alright.
18:01 MTDiscord <Benrob0329> Stating the self-evident is not useful, but info vomiting isn't either
20:51 MTDiscord <exe_virus> That's was links are for
22:07 MTDiscord <GreenXenith> I hope "some" is not a very big number, because I dont know about you but Id rather get things mostly right on the first try than have to go over all 700 entries again later
22:14 MTDiscord <Benrob0329> The currently slated docs is probably what "some" means
22:15 MTDiscord <Benrob0329> Currently, I'm trying to get Git to behave and let me fast forward the commits that don't touch mine at all but it doesn't want to let me without a merge commit
22:26 MTDiscord <josiah_wi> Rebase FTW.
22:27 MTDiscord <Benrob0329> rebases are still a PITA
22:28 MTDiscord <Benrob0329> especially when the merged PRs seem to be made up of 20 tiny commits
22:28 MTDiscord <josiah_wi> Hmm.
22:29 MTDiscord <josiah_wi> We may need to coordinate what files we work on better.
22:29 MTDiscord <Benrob0329> Well, it doesn't touch the file I wrote (vector.adoc) but git is still being picky
22:30 MTDiscord <josiah_wi> If it doesn't touch it, rebase should just fast forward. 🤨
22:31 MTDiscord <josiah_wi> The issue there is that you then would need to force push your branch I think.
22:31 MTDiscord <josiah_wi> Which is a pain.
22:31 MTDiscord <Benrob0329> eh, force pushing isn't bad
22:32 MTDiscord <josiah_wi> The best solution is probably to not merge master into your working branch. 🤣
22:39 appguru joined #minetest-docs
22:46 MTDiscord <Benrob0329> Alright, got it
22:46 MTDiscord <Benrob0329> I was using entirely the wrong commands
22:47 MTDiscord <Benrob0329> If your branch falls behind master, run git rebase master and you should be good.
23:11 appguru joined #minetest-docs
23:39 MTDiscord <josiah_wi> Do I remember correctly that it changes the commit refs of the new commits, though?
23:39 MTDiscord <josiah_wi> (Meaning you have to force push, which is something to keep in mind when collaborating.)
23:43 MTDiscord <Benrob0329> Yes, but for a PR branch that shouldn't matter much unless other people have local copies of your fork
23:58 MTDiscord <Jonathon> https://github.com/minetest/minetest/issues/11927 if we care
23:58 MTDiscord <Jonathon> (hardware coloring documentation)

| Channels | #minetest-docs index | Today | | Google Search | Plaintext