14:01:31 <bexelbie> #startmeeting Fedora Docs
14:01:31 <zodbot> Meeting started Mon Jun 26 14:01:31 2017 UTC.  The chair is bexelbie. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:01:31 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:01:31 <zodbot> The meeting name has been set to 'fedora_docs'
14:01:49 <bexelbie> #topic Roll Call
14:01:57 <terminal__> .hello t3rm1n4l
14:01:59 <zodbot> terminal__: t3rm1n4l 'None' <stealthcipher@gmail.com>
14:02:03 <bexelbie> .hello bex
14:02:04 <zodbot> bexelbie: bex 'Brian (bex) Exelbierd' <bex@pobox.com>
14:02:11 <bexelbie> it may just be the two of us, and that is ok
14:02:19 <terminal__> yep
14:02:44 <bexelbie> #topic AsciiDoc Experimental Site
14:03:04 <bexelbie> #info terminal__ has converted the SysAdmin guide from DocBook to AsciiDoc
14:03:26 <bexelbie> #link https://pagure.io/fedora-docs/asciidocs-sysadmin/
14:03:44 <bexelbie> #info the guide has been moved from that to AsciiBinder compatible in the same repo
14:04:09 <bexelbie> #info test site:  http://209.132.179.16:3000/rawhide/en-US/Book_Info.html
14:04:12 <bexelbie> #link  http://209.132.179.16:3000/rawhide/en-US/Book_Info.html
14:04:21 <bexelbie> ok, so that gets us some background
14:04:32 <bexelbie> have you had a chance to look at the test terminal?
14:04:50 <bexelbie> #info note the test site is not currently Fedora themed.  That work is mostly complete already by ryanlerch
14:04:59 <terminal__> yeah, there were some conversion issues i noted in the rawhide version, namely some refs are no longer functional, and some of the source code listings at the start of the document were formatted wrong
14:05:24 <bexelbie> have you had a chance to see if it is bad processing or bad AsciiDoc?
14:05:30 <terminal__> not yet
14:05:36 <terminal__> I just had a cursory glance
14:05:37 <bexelbie> Is that something you can do ?
14:06:14 <terminal__> I can take a look over, the references I think may be to do with the re-ordering of the document
14:06:23 <terminal__> e.g. the new folders ec
14:06:23 <bexelbie> #action terminal__ to check bad display/conversion in the test site for source code and references to see if they are asciibinder processing or AsciiDoc markup
14:06:32 <bexelbie> ok, let me know how I can help with that
14:06:36 <bexelbie> if you're ok with the action
14:06:36 <bexelbie> ?
14:06:40 <terminal__> that's fine
14:06:51 <bexelbie> I have had some fights with AsciiBinder's structure requirements
14:07:02 <bexelbie> the short versoin is that it requires the disk to look like the nesting structure of hte docs
14:07:07 <terminal__> in terms of the refs, in asciidoc they are <<refname>> [[reflabel]]
14:07:07 <bexelbie> it also changes the resolution of includes and images
14:07:21 <bexelbie> ahh, those are not going to work at all, I think
14:07:30 <bexelbie> I'll take an action item to resolve that
14:07:34 <bexelbie> as it bit me hard on the Preface
14:07:37 <bexelbie> and needs to be fixed
14:07:56 <bexelbie> The problem is that AsciiBinder processes each file separately and the refs require that the files be processed as a single batch
14:07:58 <terminal__> the reflabels need to be visible to the calling document for the references to resolve properly
14:08:02 <bexelbie> #under
14:08:05 <bexelbie> #undo
14:08:05 <zodbot> Removing item from minutes: ACTION by bexelbie at 14:06:23 : terminal__ to check bad display/conversion in the test site for source code and references to see if they are asciibinder processing or AsciiDoc markup
14:08:20 <bexelbie> #action terminal__ to check bad display/conversion in the test site for source code to see if they are asciibinder processing or AsciiDoc markup
14:08:40 <terminal__> ah right
14:08:42 <bexelbie> #action bexelbie to work with terminal__ on resolving hte best way to handle references <<ref>> [[reflabel]] in AsciiBinder
14:08:42 <terminal__> yeah
14:09:13 <bexelbie> I have a lead on how the OpenShift team handles this and would rather us start with a known solution rather than invent our own
14:09:18 <bexelbie> obviously we can change it if it doesn't work for us
14:09:19 <terminal__> in terms of the source code, I believe they were fine when I converted the document
14:09:35 <bexelbie> You had mentioned that some of the source code blocks didn't render right?
14:09:40 <bexelbie> s/right/correctly/
14:09:40 <terminal__> I think maybe asciibinder isn't liking the listing block
14:09:49 <bexelbie> do you have an example?
14:10:06 <terminal__> in the launching gui applications from a terminal
14:10:21 <terminal__> where it has the prompt and the firefox as the command
14:10:29 <terminal__> firefox is rendered under the prompt
14:10:33 <bexelbie> I see that
14:11:17 <terminal__> I'm just opening the asciidocs version to confirm it rendered fine there
14:11:55 <terminal__> ok so in asciidocs it shows '[fedorauser@localhost]$ firefox'
14:12:00 <terminal__> on a single line
14:12:00 <bexelbie> looks like it renders the code to html as a <code> inside of a <pre>
14:12:11 <bexelbie> are you using asciidoctor?
14:12:15 <terminal__> yeah
14:12:27 <bexelbie> what is the whole html output?
14:13:09 <terminal__> I'll have to convert the page, hang on a sec, I'm currently rendering it using the firefox plugin
14:14:26 <bexelbie> ok
14:15:22 <terminal__> <pre>[fedorauser@localhost]$ <code class="command">firefox</code></pre>
14:15:45 <terminal__> that's how it's rendered when converted directly from asciidocs
14:15:59 <terminal__> to html5
14:16:34 <bexelbie> if you load that file in firefox I bet you get the newline
14:16:44 <bexelbie> sounds like the firefox plugin renders AsciiDoc differently
14:17:00 <terminal__> it actually looks fine in firefox
14:17:03 <bexelbie> weird
14:17:06 <terminal__> when i open the html version
14:17:13 <terminal__> i'll try in chromium
14:17:15 <bexelbie> that is the exact line in the version on the web
14:17:18 <terminal__> coz i don't have the plugin installed
14:17:21 <terminal__> on that
14:18:03 <terminal__> still looks fine in chromium
14:18:24 <bexelbie> so I wonder why having it served via the web changes it ...
14:18:27 <bexelbie> ahh, stylesheet
14:18:33 <bexelbie> .. let me check something
14:18:36 <terminal__> ok
14:19:05 <bexelbie> I bet it is this line int he stylesheet
14:19:11 <bexelbie> .literalblock pre > code, .literalblock pre[class] > code, .listingblock pre > code, .listingblock pre[class] > code { display: block; }
14:19:18 <bexelbie> but my ability to read css is limited
14:19:25 <terminal__> yeah me too
14:19:30 <bexelbie> not a hobby of mine :P
14:19:37 <terminal__> probably more limited than you coz i've never touched it :P
14:20:10 <terminal__> could always comment it and find out :D
14:21:53 <bexelbie> I think the other way to consider this is to think about why the code is written that way
14:22:01 <bexelbie> I am not sure this is how we want to handle this specific situation
14:22:42 <terminal__> #link http://asciidoctor.org/docs/user-manual/#blocks
14:22:55 <terminal__> ^ that covers all the block styles in asciidoctor
14:23:16 <bexelbie> yes
14:23:31 <terminal__> the source code blocks are listing blocks
14:23:33 <bexelbie> but from one perspective you could say that the entire listing, prompt+command, is a single code block
14:23:34 <terminal__> e.g. ----
14:23:58 <terminal__> it's counted as a single block in asciidocs
14:23:58 <bexelbie> the command, firefox, needs to be marked as a command mostly so that we could do some automated testing on it or so we could, for example, color it differently, right?
14:24:26 <terminal__> it's marked by asciidocs as ---- [code block] ---- where the ---- is on it's own line
14:24:29 <bexelbie> so rather than have a source code block with a hard coded `literal` in it, should we consider another option?
14:25:33 <terminal__> actually i guess it's not a listing block but rather a source block, but they're technically the same
14:25:41 <terminal__> in asciidoctor
14:25:43 <bexelbie> http://www.winglemeyer.org/technology/2016/09/08/semantic-asciidoc/ has some ideas about how to semantically mark things up
14:25:56 <bexelbie> yeah, we could leave the whole things as a listing/source code block
14:25:58 <terminal__> I mean...you could use passthrough
14:26:03 <bexelbie> and then semantically identify the command
14:26:22 <terminal__> that way it ignores the text and just passes it through 'as-is'
14:26:26 <terminal__> supposedly
14:26:41 <terminal__> not sure how it would be interpreted by asciibinder
14:26:58 <terminal__> but passthrough is used to pass other markup styles through
14:27:03 <terminal__> in asciidoctor
14:27:13 <bexelbie> ----
14:27:13 <bexelbie> 
14:27:13 <bexelbie> [fedorauser@localhost]$ [command]#firefox#
14:27:13 <bexelbie> ----
14:27:48 <bexelbie> that yields <pre>[fedorauser@localhost]$ <span class="command">firefox</span></pre>
14:28:44 <terminal__> if that works, and is rendered properly i'm fine with it
14:28:44 <bexelbie> the span would let us decorate without forcing a code inside a pre
14:28:55 * bexelbie is uploading a new version to the test site
14:29:05 <bexelbie> we would need to evaluate how much of a bugger this is too fix :)
14:29:18 <bexelbie> the test site is updated
14:29:46 <terminal__> cool, that looks better
14:30:14 <bexelbie> yuck looks like there are about 1225 of these potential problems
14:30:20 <terminal__> yeah
14:30:27 <terminal__> it is pretty prevalent
14:30:36 <bexelbie> they'd need to be checked to see if they are in listings or not
14:30:38 <bexelbie> yucky
14:31:34 <terminal__> all the source code is formatted the same
14:31:37 <bexelbie> actually
14:31:40 <bexelbie> now that I think about it
14:31:47 <bexelbie> we can possibly do a search and replace on this
14:32:00 <terminal__> yeah, regex pattern matching
14:32:17 <terminal__> or something :P
14:33:19 <bexelbie> yep
14:35:11 <terminal__> regarding references, a lot of the issues appear to be basically that the refs aren't visible in the calling document
14:35:49 <terminal__> e.g. in the mail server section it refers to the installing packages section of the DNF part of the guide
14:35:56 <bexelbie> yeah, the openshift folks hit that and made a change to internal linking I need to look up
14:35:56 <terminal__> which it can't see
14:37:38 <bexelbie> I'll def research that
14:38:51 <terminal__> regarding the install guide, the conversion to asciidoctor went pretty well, there's some references missing (not sure if they just didn't carry over, or whether they were just never there) and some of the registered (R) symbols didn't render in the preface
14:39:39 <bexelbie> have you done a ton of cleanup yet?
14:39:48 <terminal__> not yet
14:39:51 <bexelbie> if not, we may be able to fix the command issue we just found in the docsii conversion
14:40:06 * bexelbie doesn't have docsii installed on this laptop but I need to get it down so I can run --help
14:40:09 <bexelbie> or could you fpaste it?
14:40:30 <terminal__> sure
14:41:34 <terminal__> https://paste.fedoraproject.org/paste/jjfMboHABsLeC2fcOsz-oA/
14:42:22 <terminal__> hmm
14:42:26 <terminal__> didn't render properly
14:42:34 <bexelbie> that's alright
14:42:36 <bexelbie> I cloned the repo
14:42:49 <bexelbie> I wonder if adding -monospace "literal,wordasword,filename,guilabel,systemitem,prompt,computeroutput,userinput,revnumber,parameter,guimenuitem,errortype,varname,function,methodname,classname,property,type,sgmltag,code,envar,guiicon"
14:42:51 <bexelbie> would change it
14:42:56 <bexelbie> to do command as a semantic markup
14:43:02 <bexelbie> not as a monospace literal
14:43:08 <bexelbie> then we do the monospacing with CSS
14:43:55 <terminal__> it's worth a try
14:44:45 <bexelbie> mind exploring that?
14:44:49 <terminal__> sure
14:45:06 <bexelbie> I am expecting you to get "[command]#foo#" instead of "[command]`foo`"
14:45:18 <bexelbie> great catch!
14:45:28 * bexelbie hadn't noticed the new line at all
14:46:58 <terminal__> all the time i spent looking for errors helped, I'm quite familiar with the document formatting now :P
14:49:14 <bexelbie> hahah
14:49:15 <bexelbie> I bet
14:49:22 <terminal__> One of the issues i raised against the repo was that in the guide it mentions the Security Guide
14:49:30 <terminal__> which hasn't been updated since F19
14:49:39 <bexelbie> #action terminal__ to test -monospace  "literal,wordasword,filename,guilabel,systemitem,prompt,computeroutput,userinput,revnumber,parameter,guimenuitem,errortype,varname,function,methodname,classname,property,type,sgmltag,code,envar,guiicon" with the install guide
14:49:55 <bexelbie> #action bexelbie to fix the sysadmin guide [command]` stuff
14:49:58 <bexelbie> ok?
14:50:10 <terminal__> it's mentioned a few times
14:50:13 <bexelbie> terminal__, re: security guide - yeah that is a problem - and a good thing to raise
14:50:22 <bexelbie> I hope we can get others to fix that once we get the source publishable
14:50:28 <bexelbie> as it will be inspirational :)
14:50:32 * bexelbie is a dreamer some days
14:50:36 <terminal__> haha
14:50:46 <terminal__> it would be quite outdated now
14:50:52 <terminal__> at present
14:51:11 <bexelbie> I think the right answer may be to delete the referneces
14:51:43 <terminal__> maybe...although security is important
14:51:49 <terminal__> haha
14:52:09 <terminal__> I mean we could ref the rhel security guide i suppose
14:52:28 <terminal__> but some of that may be not as relevant
14:52:31 <terminal__> either
14:52:44 * terminal__ *shrug*
14:53:45 <terminal__> like most of the docs, it needs an update
14:54:34 <terminal__> also Fedora 19 is mentioned in the web server section of the sysadmin guide
14:54:40 <bexelbie> we can't reference the RHEL guide for several reasons
14:54:50 <terminal__> interesting
14:54:51 <bexelbie> I think what we can do is to encourage the update of hte security guide
14:54:58 <bexelbie> or use it as a test bed for topics
14:54:58 <terminal__> true
14:55:05 <bexelbie> and have people rescue the topics hta tmatter from it
14:55:13 <bexelbie> so we can delete the old references here and in install
14:55:14 <terminal__> the rhel security guide has been referenced in the sysadmin guide a few times
14:55:15 <bexelbie> imho
14:55:21 <bexelbie> we should really not be doing that
14:55:23 <bexelbie> :)
14:55:40 <terminal__> I know that now, although I never put them in there
14:56:00 <terminal__> they were already there, however some of the locations had changed, so i updated the web links
14:56:07 <terminal__> re: the rhel storage guide
14:56:40 <bexelbie> that is a good start
14:56:46 <bexelbie> we can't eat the elephant in one bite
14:56:57 <bexelbie> we have about 4 min left and I need to drop a bit early
14:57:06 <bexelbie> do we need to talk about anything else specific in this meeting?
14:57:12 * bexelbie will be online for a few more hours, just in meetings
14:57:44 <terminal__> I don't think so, as we discussed, content, updates, trying that docscii switch
14:57:51 <bexelbie> sounds good then
14:57:52 <terminal__> pretty much covered everything i think
14:57:56 <bexelbie> thank you for this work so far
14:58:03 <bexelbie> I'll try to get the theming in place soon so you can see that too
14:58:07 <terminal__> no probs
14:58:20 <bexelbie> terminal__++
14:58:28 <bexelbie> #endmeeting