16:01:51 <acozine> #startmeeting DaWGs aka Docs Working Group
16:01:51 <zodbot> Meeting started Tue Dec 15 16:01:51 2020 UTC.
16:01:51 <zodbot> This meeting is logged and archived in a public location.
16:01:51 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:01:51 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:51 <zodbot> The meeting name has been set to 'dawgs_aka_docs_working_group'
16:01:55 <acozine> #topic opening chatter
16:01:57 <acozine> who's around?
16:02:06 <acozine> #chair dmsimard samccann
16:02:06 <zodbot> Current chairs: acozine dmsimard samccann
16:02:14 <dmsimard> \o
16:02:27 <dmsimard> abadger1999 maybe :)
16:02:30 <samccann> o/
16:02:30 <acozine> dmsimard: morning, and thanks for reporting the build errors
16:02:48 <abadger1999> Good morning :-)
16:02:55 * dericcrago waves
16:03:28 <acozine> abadger1999: dericcrago gundalow andersson007_ briantist cyberpear felixfontein madonius persysted tadeboro you chatting docs today?
16:03:36 <acozine> #chair abadger1999 dericcrago
16:03:36 <zodbot> Current chairs: abadger1999 acozine dericcrago dmsimard samccann
16:03:39 <acozine> good morning!
16:03:54 <felixfontein> I'm around!
16:04:07 <acozine> afternoon felixfontein!
16:04:10 <acozine> #chair felixfontein
16:04:10 <zodbot> Current chairs: abadger1999 acozine dericcrago dmsimard felixfontein samccann
16:04:32 <felixfontein> morning abadger1999!
16:04:59 * gundalow waves
16:05:13 <abadger1999> good afternoon felixfontein !
16:05:22 <acozine> #chair gundalow
16:05:22 <zodbot> Current chairs: abadger1999 acozine dericcrago dmsimard felixfontein gundalow samccann
16:05:24 <samccann> full house!
16:05:47 <acozine> #topic holiday schedule
16:06:48 <acozine> We will cancel the DaWGs meetings for the week of Dec. 28-Jan 1.
16:07:33 <acozine> We can also cancel next week's meetings. Will anyone be around next Tuesday? I will be working, I know samccann will be out . . .
16:08:25 <felixfontein> no idea actually :)
16:08:43 <felixfontein> I'm probably around
16:09:02 <acozine> okay, we can have a DaWGs Holiday Edition meeting, and see on the day if anyone turns up
16:09:21 <acozine> if nothing else, I'll post my recipe for home-made egg nog
16:09:33 <felixfontein> :)
16:10:18 <acozine> #agreed Meetings cancelled Dec. 24, Dec. 29, and Dec. 31
16:10:29 * gundalow will not be here next week
16:10:35 <abadger1999> :-)
16:10:41 <tadeboro> I will be a passive lurker today since it looks like I managed to get a copy of that nasty COVID thingy. But I guess with my wife working in healthcare, this is kind of expected.
16:10:48 <acozine> #agreed Meeting Dec. 22 will happen but will be very informal
16:11:05 <acozine> tadeboro: sorry to hear that! take care of yourself
16:11:16 <samccann> oh gosh.. take care tadeboro !
16:11:50 <abadger1999> tadeboro: Oh, I'm sorry that's happened :-(
16:12:27 <dmsimard> tadeboro: take care :(
16:12:44 <felixfontein> tadeboro: get well soon!
16:14:17 <tadeboro> I'll be fine. Being a doctor in previous life (before mathematitian) helps in such situations.
16:14:45 <tadeboro> And in previous life I mean "10 years ago when I switched careers".
16:14:49 <samccann> nice backstory !
16:14:50 <felixfontein> :)
16:15:14 <acozine> sadly IRC is not a good pipeline for sending soup ;-(
16:15:16 <dmsimard> troubleshooting computers is easier than troubleshooting humans
16:15:53 <acozine> computers are more consistent
16:16:21 <acozine> #topic linking in module index pages
16:16:27 <felixfontein> if they don't have bad electronics in them
16:16:42 <bcoca> acozine: at least you can get the letters, though you are missing the liquid part
16:16:56 <acozine> #chair bcoca
16:16:56 <zodbot> Current chairs: abadger1999 acozine bcoca dericcrago dmsimard felixfontein gundalow samccann
16:17:38 <acozine> words can be both comforting and heartening, but they aren't very nourishing
16:18:00 <samccann> Ansible Chicken Soup for the Soul??
16:18:07 <acozine> but comfort, heart, and nourishment all help folks heal, so we'll do what we can
16:18:20 <acozine> heh
16:18:37 <dmsimard> let's go back on topic :D
16:18:54 <acozine> does anyone know how to fix the failures on https://github.com/ansible/ansible/pull/72743
16:19:29 <acozine> error is `docs/docsite/rst/collections/all_plugins.rst:0:0: File was not added to sdist`
16:21:12 <acozine> it seems like https://github.com/ansible/ansible/pull/72743/files#diff-41d5a52589e0480be9c099d2bba7a8135b8b0d71bcbb8df3582a8df1c2295003 should fix the error
16:21:15 <abadger1999> That's happening during the docs build?  Or as part of the sanity tests?
16:21:22 <acozine> but apparently it doesn't
16:21:45 <felixfontein> abadger1999: sanity tests
16:21:47 <acozine> abadger1999: the Azure Pipelines output is new to me, but it looks like it's happening in both places
16:21:57 * abadger1999 gets used to the azure interface
16:22:00 <felixfontein> abadger1999: might also go wrong during release
16:22:53 <acozine> oh, no, it's the same sanity-test failure in both places
16:23:51 <abadger1999> Doesn't seem to be much information in the azure interface.
16:24:09 <abadger1999> But I'll run the sanity test on that PR locally and see if I can figure it out
16:24:20 <felixfontein> abadger1999: it's essentially the log output: https://dev.azure.com/ansible/ansible/_build/results?buildId=2103&view=logs&jobId=6b8fca62-2c63-5c74-2051-15ea31c8c104&j=6b8fca62-2c63-5c74-2051-15ea31c8c104&t=e6a77036-d6ac-54d6-bbbb-976ea775a86e
16:27:54 <acozine> The test "Verifies that the combination of MANIFEST.in and package_data from setup.py properly installs data files from within lib/ansible"
16:28:07 <acozine> but I don't think we want to install that file in lib/ansible
16:28:30 <abadger1999> <nod>
16:29:00 <abadger1999> The test should be complaining only if the new file isn't included i nthe ansible-base tarball.
16:29:27 <abadger1999> Explicitly adding it to the MANIFEST should *definitely* ensure that it is in the tarball.  So something unexpected is happening.
16:29:37 <abadger1999> I will troubleshoot this.
16:29:44 <acozine> thanks abadger1999
16:29:47 <felixfontein> abadger1999: thanks!
16:29:49 <abadger1999> Up to you if you want to watch me do that during this meeting or move on :-)
16:30:00 <acozine> let's see if we can fit some other topics in
16:30:16 <felixfontein> I guess moving on is a good idea, since we have other topics?
16:30:40 <dmsimard> my renders are ready to show fwiw
16:30:44 <acozine> Most of them are follow-up
16:31:00 <acozine> agenda: https://github.com/ansible/community/issues/521#issuecomment-741007843
16:31:20 <acozine> dmsimard: remind us what those are?
16:31:42 <dmsimard> action from last meeting: @dmsimard to draft 5 example renders of options in #521 (comment) + B(option)=C(value) to help vote at a later meeting
16:32:01 <acozine> oh, awesome, that dovetails with the agenda
16:32:16 <acozine> #topic update on module formatting for option: value
16:32:41 <dmsimard> ok let me get copy/pasta ready
16:32:43 <acozine> dmsimard: thanks for doing those! do you have a link?
16:33:02 <dmsimard> so there were 5 options to look at and I added a 6th one for fun
16:33:17 <acozine> the more the merrier at this stage
16:33:37 <dmsimard> for reference (let's call it 0), the current docs: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/lineinfile_module.html
16:33:45 <dmsimard> 1. I(option=value) https://dmsimard.com/files/docsite/1/collections/ansible/builtin/lineinfile_module.html
16:33:50 * gundalow -> Other meeting
16:33:50 <dmsimard> 2. C(option=value) https://dmsimard.com/files/docsite/2/collections/ansible/builtin/lineinfile_module.html
16:33:55 <dmsimard> 3. I(option)=C(value) https://dmsimard.com/files/docsite/3/collections/ansible/builtin/lineinfile_module.html
16:34:01 <dmsimard> 4. I(option=)C(value) https://dmsimard.com/files/docsite/4/collections/ansible/builtin/lineinfile_module.html
16:34:06 <dmsimard> 5. B(option)=C(value) https://dmsimard.com/files/docsite/5/collections/ansible/builtin/lineinfile_module.html
16:34:42 <dmsimard> 6. C(option: value) but just found out my render failed :/
16:34:52 <acozine> okay, so the text to compare is `Used with state=present.`
16:35:03 <dmsimard> yes, exactly
16:35:10 <acozine> ignoring the fact that it should be `state: present` . . . but that's a different problem
16:35:19 <acozine> this is all about how it looks!
16:35:45 <dmsimard> so the current docs, at least for lineinfile, is format #2
16:36:40 <felixfontein> it should be in format #1 according to our docs, though, right?
16:37:18 <dericcrago> I like #2 (but would probably like #6 better if I could see it ;) )
16:37:56 <dmsimard> felixfontein: correct according to https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#linking-and-other-format-macros-within-module-documentation
16:38:07 <samccann> option #5 is, if I recall, what IBM style guide says it should be
16:38:22 <samccann> according to last weeks meeting minutes :-)
16:38:22 <acozine> heh, well, #6 is the same as #2, just with updated text, right? or did you transform the existing text when you built it, so that `state=present` gets changed to `state: present`
16:38:43 <dmsimard> acozine: yeah 6 would be the same replacing the "=" with ": "
16:38:50 <dmsimard> the same as 2*
16:38:52 <acozine> samccann: I think IBM style guide allows #2 "when text is meant to be copied and pasted"
16:39:16 <samccann> ah yes, thanks,...phew
16:39:18 <abadger1999> Is #6 going to be hard on editors (because it involves a colon which has syntactic meaning to yaml)?
16:39:25 <acozine> dmsimard: I think we might get into trouble replacing every instance of `=` with `:`
16:39:32 <samccann> cuz I prefer 2 to 5 for sure
16:39:41 <dmsimard> when trying to do 6, the render failed with https://dmsimard.com/files/docsite/6/collections/ansible/builtin/lineinfile_module.html
16:39:53 <abadger1999> (I'm guessing that's also why the render failed ;-)
16:40:00 * dmsimard nods
16:40:39 <felixfontein> you probably needed to add quotes to keep the descriptions being strings, and not become dictionaries :)
16:40:52 <abadger1999> Yeah, likely means that the summary of the option became a dict due to the colon instead of being a string
16:41:02 <abadger1999> jinx :-)
16:41:10 <dmsimard> not 100% sure I follow
16:41:18 <dmsimard> so C(option: value) should be ... C("option: value") ?
16:41:19 <felixfontein> that's one of the most common problems with changelog fragments and documentation ;)
16:41:23 <bcoca> yaml treats  :  special
16:41:30 <felixfontein> dmsimard: no, `- "blabla C(option: value) blabla"
16:41:34 <felixfontein> `
16:41:38 <bcoca> ^ quotes needed
16:41:43 <dmsimard> ah, that could be bothersome
16:41:53 <bcoca> s/could be/is/
16:41:57 <acozine> heh
16:42:23 <dmsimard> so with that in mind my personal preference would be #2
16:42:36 <acozine> mine too
16:42:45 <acozine> let's see, how do we vote on something with 6 options?
16:42:58 <felixfontein> mine is 3 or 4, to keep consistent formatting for option names and values
16:44:18 <felixfontein> one question about 2. is how to actually write it in the documentation. using names like I/C/B, which are display indicators, for logical things like option name, option value etc. is really not great
16:44:20 <acozine> don't we use `C(name)` for standalone option names elsewhere?
16:44:28 <felixfontein> acozine: no, we use I(name)
16:44:30 <dmsimard> acozine: can start by narrowing down options and eliminate those no one is in favor of :)
16:45:01 <felixfontein> one of 3 and 4 should definitely go
16:45:47 <dmsimard> 4 includes the "=" into the italic whereas 3 doesn't
16:45:58 * acozine looks again at the current docs
16:46:08 <acozine> ```
16:46:10 <acozine> erg
16:46:31 <acozine> We currently say: `C() for files and option values. For example: If not set the environment variable C(ACME_PASSWORD) will be used. This displays with a mono-space font in the documentation.`
16:46:58 <acozine> ah, okay, so that's meant only for VALUES
16:47:39 <dericcrago> fwiw, I believe using the multiline options (like > | ) would get around the : rendering issue without quotes all over the place
16:48:03 <felixfontein> dericcrago: it does, but it can blow up documentation (if it fitted into one line before)
16:48:37 <felixfontein> OTOH it makes it clearer that a new item is in fact a new paragraph
16:48:57 <felixfontein> (since there's more vertical separation between two list items then)
16:51:09 <dmsimard> so let's recap: the current documented standard is option #1 I(option=value) https://dmsimard.com/files/docsite/1/collections/ansible/builtin/lineinfile_module.html  (in spite of which upstream lineinfile is currently using #2)
16:51:51 <acozine> yes
16:51:53 <felixfontein> I sometimes wonder whether the standard switched in the past, because there are quite some modules which use(d) I and C reversed
16:51:54 <dmsimard> is anyone in favor of #1 ?
16:52:21 <dmsimard> #chair
16:52:21 <zodbot> Current chairs: abadger1999 acozine bcoca dericcrago dmsimard felixfontein gundalow samccann
16:52:25 <felixfontein> I prefer #1 over #5 (if regular options stay with I)
16:53:13 <acozine> do we need ranked choice voting?
16:53:46 <samccann> heh
16:53:58 <felixfontein> depending what 5 means for regular option names (without a value)
16:54:11 <dmsimard> I don't dislike #5 because the options are bold already (like "state" in the Parameter column)
16:54:29 <felixfontein> dmsimard: but they are not anywhere else in the documentation
16:54:56 <felixfontein> and bold shouldn't be used excessively
16:55:03 <dmsimard> I don't disagree
16:56:49 <acozine> I like #2 because it makes the docs look the way a user's playbook would look
16:57:04 <dmsimard> with the exception of s/=/: /
16:57:07 <acozine> heh
16:57:20 <acozine> yeah, there's that
16:57:35 <abadger1999> If we bold the option names for this, I'd change the guideline of `I(option_name)` to `B(option_name)` for consistency
16:58:01 <acozine> but we have the `=` => `:` problem no matter what formatting we use, right?
16:58:22 <felixfontein> if we want to change all existing documentation, could we please stop using I/C/B for indicating semantics, and introduce new names, like O(...) for option names?
16:58:30 <abadger1999> yes, I think so.
16:58:36 <samccann> yes we should separate that out from the formatting discussion ( = vs : )
16:58:45 <samccann> felixfontein++
16:58:49 <abadger1999> felixfontein: <nod>
16:58:53 <dmsimard> apologies for introducing that sixth option :)
16:58:59 <acozine> that makes sense
16:59:13 <dmsimard> felixfontein: agreed, so if we change our mind later we don't need to reformat everything
16:59:13 <samccann> yes, if we are going to have to edit most modules for this - we should name them for what they are not what we render. Gives us the option to change rendering later
16:59:26 <felixfontein> if we use O(...) for options consistently, we can easily change the look in the future without having to go through all documentation
16:59:28 <acozine> dmsimard: it was worth a try!
16:59:43 <felixfontein> dmsimard: samccann: exactly :)
16:59:51 <dmsimard> felixfontein: how would that work in practice ? O(foo=bar) ?
17:00:12 <dmsimard> or O(foo)=C(bar) ?
17:00:35 <felixfontein> dmsimard: that we can define. `O(foo)` for option named `foo`, and converting `O(foo: bar)` or `O(foo=bar)` to something else can be done by the renderer (i.e. antsibull, ansible-doc, ...)
17:00:39 <dmsimard> or even O(foo)=V(bar)   <-- v for value
17:00:47 <acozine> maybe `O(foo)` and `V(bar)`?
17:01:05 <samccann> yes, something like that ^^
17:01:10 <acozine> dmsimard: yeah, if we want them to render differently
17:01:32 <felixfontein> sounds good. then we can use C(...) for other stuff that's not a value, and also use I(...) and B(...) for proper formatting :)
17:01:34 <samccann> still leave I/B/ for those who want italics and bold somewhere. But give the rest real names so to speak
17:01:51 <samccann> i'm up in the air on C
17:02:05 <samccann> what does it mean (besides what it renders as)?
17:02:14 <dmsimard> I don't see a need to remove I/B/C as a result of doing this, they can stay
17:02:22 <dmsimard> it's "render this as monospace code"
17:02:24 <acozine> C for Code, i think
17:02:41 <acozine> like I and B, I think that's a more-than-Ansible convention
17:03:03 <dmsimard> it's equivalent to markdown ``this is code``
17:03:27 <dmsimard> rst too, in fact
17:03:29 <samccann> the value of changing to O() and V() is we are naming things as they are. In the future, we can choose to render them differently w/o changing everything again
17:03:38 <felixfontein> that's rst, in markdown it is `...`
17:03:53 <dmsimard> ah, I might be mixing up my rst and md :)
17:03:59 <acozine> yes, if we're changing everything (again) we should build in flexibility for the future
17:04:03 <samccann> C() is code makes sense. But then how is C() used today?
17:04:42 <felixfontein> samccann: it's essentially used for everything, like file names, environment variables, option values, generic code fragments, ...
17:04:42 <acozine> does anyone object to creating `O()` and `V()` (or just `O()` if we want simplicity)?
17:05:04 <samccann> -1 for simplicity
17:05:08 <acozine> heh
17:05:11 <felixfontein> :)
17:05:16 <samccann> either we name them for what they are, or we stick w/ I/B/C
17:05:24 <samccann> going 1/2 way doesn't solve much.
17:05:37 <samccann> I'm fine if we want to stick to I/B/C.
17:06:09 <felixfontein> I don't mind adding `V` as well
17:06:10 <samccann> or if we want to call option=value something new/specific
17:06:14 <dmsimard> samccann: C() usage: https://codesearch.recordsansible.org/?q=C%5C(&i=nope&files=&repos=
17:06:25 <felixfontein> then C can be used for everything that's not an option value, like env variables, filenames, ...
17:06:32 <dmsimard> er, my irc client borked the parsing of that link, might need to copy/paste
17:06:33 <samccann> like 'use V(option:value)' and call it a day
17:07:18 <felixfontein> samccann: hmm if you want to say that `option` has value `value`, that's not good
17:07:35 <felixfontein> because there's no way to distinguish it from the option value `option:value`
17:09:00 <abadger1999> There are drawbacks
17:09:07 <felixfontein> if we want to specify both option + value, we should use O() for that
17:09:11 <abadger1999> The parser for this stuff is extremely naive
17:09:16 <abadger1999> It's just a pattern match
17:09:54 <felixfontein> abadger1999: but it won't be worse than the current situation, right?
17:10:13 <abadger1999> So right now, if I have "ABC(The ABC Corporation)"  in my documentation string, it would get rendered as "AB<pre>The ABC Corporation</pre>"
17:10:23 <acozine> What's our goal? Is it: "As a docs user, I should be able to tell the difference between option names and option values, and also distinguish both of those from other things like environment values or file names."
17:10:34 <abadger1999> Adding more of these will increase the liklihood of conflicts
17:10:52 <samccann> I thought the original issue was someone found the italics hard to read
17:11:08 <abadger1999> I don't know if that's a big enough reason to not add more, but we should be aware of it whenever we add something.
17:11:32 <dmsimard> felixfontein originally brought up the topic: https://github.com/ansible/community/issues/521#issuecomment-739263018
17:11:57 <felixfontein> the original italics vs. <code> comment was by sdoran
17:12:32 <sdoran> I have opinions. :)
17:12:38 <acozine> #chair sdoran
17:12:38 <zodbot> Current chairs: abadger1999 acozine bcoca dericcrago dmsimard felixfontein gundalow samccann sdoran
17:12:55 <felixfontein> abadger1999: the regex has a \b before the capital letter, so ABC(xxx) won't match
17:13:11 <dmsimard> sdoran: if you scroll up a bit you have 5 options and links that I pasted -- have a look and see if there's one that stands out for you ?
17:14:50 <abadger1999> ah, maybe I added that during hte big revamp for 2.10
17:15:03 <abadger1999> or maybe I complained and someone else added it ;-)
17:15:11 <acozine> heh
17:15:45 <felixfontein> abadger1999: I think you did, but I don't remember that well anymore
17:16:18 <acozine> How important is distinguishing between option names and option values?
17:16:23 <acozine> in the docs, I mean
17:16:59 <abadger1999> I feel like if we're making it semantic rather than purely formatting, O() vs V() is important.
17:17:00 <felixfontein> when not specified together (`option=value` or `option: value`)? I think it is important.
17:17:26 <dmsimard> need to step away momentarily, be back in a few
17:18:51 <abadger1999> Like what if you have O(irc_nick)=V(abadger1999) when talking to abadger, V(felixfontein) if you need felixfontein, and V(acozine) to make sure acozine gets pinged.
17:19:35 <acozine> yeah, we do have that in many places in the docs
17:19:36 <felixfontein> and distinguishing between the option name O(force) and the option value V(force) can also be critical
17:19:38 <abadger1999> I guess that's an example of felixfontein's thought
17:20:01 <felixfontein> abadger1999: thanks :)
17:20:16 <felixfontein> O(irc_nick=abadger1999) would also be ok IMO, since this can be automatically converted
17:20:23 <abadger1999> Would V() be abused for more than option values?  And do we care?
17:20:44 <acozine> I tend to use words/sentence structure to make that clear, rather than formatting
17:21:02 <acozine> but maybe formatting would be better
17:21:02 <abadger1999> like, C(ANSIBLE_LIBRARY_PATH)=V(/usr/share/ansible/modules)
17:21:09 <felixfontein> acozine: not everyone is that good at wording ;)
17:21:41 <samccann> semantic labelling is common in techdocs for these very reasons
17:22:09 <acozine> yeah, that makes sense
17:22:24 <samccann> but then we have what is used in module docs vs what is used in rst docs
17:22:39 <samccann> aka rst afaik doesn't have semantic labels either
17:22:57 <acozine> it does for some things, I think
17:23:02 <abadger1999> sphinx does have semantic labels
17:23:13 <abadger1999> The sphinx way would be to use a domain/role
17:23:21 <samccann> and we have some 70+ repositories now for all this info.  This seems a big task
17:23:43 <samccann> so my question is - is the effort worth the outcome?
17:23:45 <abadger1999> like :py:class:`AnsibleModule`
17:24:17 <felixfontein> samccann: if we use new names (O, V), at least progress is measurable :)
17:24:55 <acozine> sdoran: you started us down this path, what do you think?
17:24:58 <sdoran> My main thought is that text formatting is meant to convey meaning. Italic and bold are meant to call attention to the reader for emphasis. Inline code formatting should be used to indicate values that will be used in YAML or on the command line.
17:25:04 <dmsimard> I'm back
17:25:22 <dmsimard> samccann: not just 70+ repositories, I guess we'd also need to go through maintained stable branches
17:25:35 <sdoran> I don't think it's particularly useful to distinguish between option and value in _formatting_, because they both get used in code or as a CLI arg.
17:27:16 <sdoran> And to be clearer, this only only for formatting within the Comments section or other prose where k=v, or k, or v is referenced.
17:27:16 <abadger1999> So you'd be more inclined towards something like, "Change almost everything from C(), I(), and B() into C()'  where almost everything is "things used verbatim in playbooks or on the CLI"
17:27:26 <sdoran> Ye
17:27:29 <sdoran> Yes.
17:27:40 <sdoran> To me, that's what the formatting is meant to convey.
17:28:08 <samccann> so we could drop I and B, and convert every use of it to C in the pipeline rendering?
17:28:19 <samccann> (as in not go back and fix it all?)
17:28:24 <dmsimard> sdoran: so that'd be example #2 C(option=value) https://dmsimard.com/files/docsite/2/collections/ansible/builtin/lineinfile_module.html
17:29:09 <sdoran> I and B are useful for emphasis in other contexts.
17:29:41 <sdoran> dmsimard: Yes. Though I think `lsattr` and `chattr` should also be inline code rather than italic on that page as well.
17:30:58 <abadger1999> Some things could be done at render time (ie: both O(option_name) and V(value) could be rendered inside of <pre>, like C() is currently)   but  O(option_name)=V(value) would look a little funny if we did that at render time rather than in the docs themselves.
17:31:49 <abadger1999> C(option=value) is easier for the writer to remember to do than having multiple pieces of markup.
17:32:34 <sdoran> I think that (O()=V()) would look funny. Probably not work the extra effort to distinguish the formatting.
17:32:57 <sdoran> s/work/worth
17:33:02 <abadger1999> samccann: The O() & V() vs all C()   line would also apply to rendering I() and B() the same way as C() I think.
17:33:39 <abadger1999> samccann: but that's probably a case where over half of the usage will look ifne and we just want to convert the other 30% or so when a user reports that the formatting is off.
17:34:48 <abadger1999> samccann: Although..... I'm not sure if we should do that?  It means no one can get italics or bold to render in the docs until (if ever) we change the rendering back.
17:36:17 <samccann> heh
17:36:18 <abadger1999> Swtiching everything to C() does go against the trend in documentation to forgo explicit formatting in favor of semantic markup.
17:37:09 <abadger1999> But I don't know enough about documentation theory to argue for or against in this case.
17:37:24 <samccann> yep. just depends how far down the semantic path we want to go and will contributors unerstand it if we still have I and B
17:38:29 <acozine> Can we figure out how many lines would need changing if we go to `C()` for all YAML-and/or-command-line-text and preserve the ability to make other text italic or bold?
17:39:29 <acozine> If we create full-on semantic markup, we  would have to change everything
17:39:40 <felixfontein> I don't like switching everything to C()
17:40:01 <acozine> felixfontein: because of option names /values?
17:40:22 <acozine> s/because of/ONLY because of
17:42:45 <felixfontein> acozine: first that, and second I really like semantic markup
17:43:23 <acozine> okay, can we create a proposal, with some idea of how much work it would be to move to full semantic markup?
17:43:50 <abadger1999> It can also be "Old way, deprecated, new way, preferred"
17:44:04 <acozine> yeah, we can implement over time
17:45:30 <acozine> next steps?
17:45:36 <acozine> we're at 1 hour 45
17:45:46 <acozine> and I need a lunch break ;-)
17:46:58 <abadger1999> So proposal should be easy.  Estimating work will be harder.
17:47:41 <abadger1999> I could probably give statistics on how many `I()`, `C()` and `B()` entries there are i nthe ansible docs build
17:47:45 <abadger1999> Does that sound good?
17:47:52 <acozine> abadger1999: that sounds great
17:47:55 <abadger1999> I'll take the action item if so.
17:48:18 <acozine> #action abadger1999 to figure out how many formatted entries we have in the ansible docs build
17:48:24 <abadger1999> Cool
17:49:25 <acozine> I like semantic markup, it's clear and useful. However, it can be high-maintenance.
17:49:26 <felixfontein> the advantage is that every collection that migrated to the new names can use I/C/B for other purposes without feeling guilty :)
17:49:40 <acozine> true
17:49:51 <acozine> all right, quick open floor
17:50:03 <acozine> before I start eating my desk ;-)
17:50:10 <acozine> #topic open floor
17:50:30 <felixfontein> maybe we should have some kind of escape mechanism for V() and O(), to allow using brakets inside
17:50:34 <acozine> all questions, comments, suggestions, problems, ideas, pull requests, issues welcome
17:50:38 <felixfontein> adding that to C() is essentially impossible without breaking things
17:52:08 <acozine> felixfontein: brackets? `{`? or colons? `:`?
17:52:33 <acozine> if we could escape the `:` within `V()` that would be a big incentive to adopt it
17:53:30 <felixfontein> acozine: why escape `:` in `V()`?
17:53:39 <abadger1999> <nod>
17:53:58 <acozine> so we could convert all the `var=val` to `var: val`
17:54:43 <felixfontein> acozine: why not use O() for everything that involves option names? and V() just for values?
17:55:01 <felixfontein> that would avoid a lot of complication, like when you actually want to use a `=` or `:` inside a value
17:55:08 <felixfontein> (which can happen)
17:55:36 <felixfontein> just think of docker_container's `volumes` option, where you specify `/path:/other/path:options` values.
17:55:57 <acozine> heh, another reason to escape those pesky `:`s
17:56:23 <abadger1999> I don't think we can escape :
17:56:28 <acozine> sigh
17:56:44 <abadger1999> because the order of parsing is python parsing, then yaml parsing, then the docs build parsing.
17:56:57 <abadger1999> : is special to the yaml parsing.
17:57:07 <abadger1999> So you have to use yaml escape methods to deal with it.
17:57:15 <felixfontein> hmm, I think we are talking about different things here
17:57:23 <acozine> heh, okay, quotation marks it is, or we stick with `=`
17:57:32 <felixfontein> with escaping, I mean that I can write `a(b)` as a value.
17:57:44 <felixfontein> right now, I cannot do that, since `)` is taken as the end of `C(`
17:57:52 <abadger1999> <nod> Yeah.  that we can do
17:58:01 <dericcrago> ':' is only a problem during the yaml parsing if it is followed by a space
17:58:04 <felixfontein> so `C(a(b))` will end up as `a(b` formatted as code, and `)` formatted regularly
17:58:24 <acozine> yeah, I've seen that in the docs, I thin
17:58:27 <acozine> think
17:58:38 <acozine> sorry, I have to end the meeting
17:58:56 <acozine> we'll come back to this topic
17:59:02 <acozine> either next week or in January
17:59:11 <acozine> thanks abadger1999 bcoca dericcrago dmsimard felixfontein gundalow samccann sdoran
17:59:12 <felixfontein> +1
17:59:17 <felixfontein> thanks everyone as well!
17:59:22 <acozine> #endmeeting