From w.david.ashley at gmail.com Mon Jun 22 10:17:57 2015 Content-Type: multipart/mixed; boundary="===============3059681050969782630==" MIME-Version: 1.0 From: David Ashley To: docs at lists.fedoraproject.org Subject: Code Examples in Documents Date: Sun, 21 Jun 2015 11:16:46 -0500 Message-ID: <5586E36E.1030508@gmail.com> --===============3059681050969782630== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable All - In the past when creating a new document that will contain code examples = in C/C++ or Python I always placed the examples in separate files from = the main XML. This way it would be easier to test those examples to make = sure that they work as intended. Being new to the Fedora Docs team I = have looked at some of the current documents and they do not seem to = separate the code from the document itself. So I am wondering if I = should follow that convention or separate the code from the XML like I = have done in the past? Please provide some guidance. David Ashley --===============3059681050969782630==-- From wb8rcr at arrl.net Mon Jun 22 10:17:57 2015 Content-Type: multipart/mixed; boundary="===============3756878360712235858==" MIME-Version: 1.0 From: John J. McDonough To: docs at lists.fedoraproject.org Subject: Re: Code Examples in Documents Date: Sun, 21 Jun 2015 13:02:02 -0400 Message-ID: <1434906122.16507.56.camel@Aidan> In-Reply-To: 5586E36E.1030508@gmail.com --===============3756878360712235858== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable I don't see an issue with that, as long as the code fragments are in the same repository. Actually sounds like a pretty decent idea. *BUT*, I do see some potential issues. Some characters common in code are interpreted by DocBook, even within or tags, so you would have to doctor your included file to make it uncompileable. Worse, some initial tinkering (probably you should experiment more) indicates that neither tag carries into an included file, and DocBook doesn't seem to want to include other extensions. Perhaps there are some workarounds, because to me, it sounds like a good idea, but there might be some practical issues to sort out. --McD On Sun, 2015-06-21 at 11:16 -0500, David Ashley wrote: > All - > = > In the past when creating a new document that will contain code examples = > in C/C++ or Python I always placed the examples in separate files from = > the main XML. This way it would be easier to test those examples to make = > sure that they work as intended. Being new to the Fedora Docs team I = > have looked at some of the current documents and they do not seem to = > separate the code from the document itself. So I am wondering if I = > should follow that convention or separate the code from the XML like I = > have done in the past? > = > Please provide some guidance. > = > David Ashley --===============3756878360712235858==-- From harvey at eccnet.com Mon Jun 22 10:17:57 2015 Content-Type: multipart/mixed; boundary="===============3283231735638888308==" MIME-Version: 1.0 From: Betty Harvey To: docs at lists.fedoraproject.org Subject: Re: Code Examples in Documents Date: Sun, 21 Jun 2015 13:59:15 -0400 Message-ID: In-Reply-To: 5586E36E.1030508@gmail.com --===============3283231735638888308== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable You can put code into the XML document by using CDATA sections. = Anything in a CDATA section is ignored by the parser so you can put = characters that you normally cannot add to an XML document, i.e., less = than, greater than, etc. Below is how a CDATA section is constructed for the Docbook example = element: My Code CDATA Section

Anything in a CDATA section is ignored by the XML Parser.

]]>
The parser will also respect any white space in the CDATA section so = what you see will be what you get inside the section. Hope this helps! Betty On 2015-06-21 12:16, David Ashley wrote: > All - > = > In the past when creating a new document that will contain code > examples in C/C++ or Python I always placed the examples in separate > files from the main XML. This way it would be easier to test those > examples to make sure that they work as intended. Being new to the > Fedora Docs team I have looked at some of the current documents and > they do not seem to separate the code from the document itself. So I > am wondering if I should follow that convention or separate the code > from the XML like I have done in the past? > = > Please provide some guidance. > = > David Ashley -- = /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/ Betty Harvey | Phone: 410-787-9200 FAX: 9830 Electronic Commerce Connection, Inc. | harvey(a)eccnet.com | Washington,DC XML Users Grp URL: http://www.eccnet.com | http://www.eccnet.com/xmlug /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\\/\/ Member of XML Guild (www.xmlguild.org) --===============3283231735638888308==-- From wb8rcr at arrl.net Mon Jun 22 10:17:57 2015 Content-Type: multipart/mixed; boundary="===============8934202832634129517==" MIME-Version: 1.0 From: John J. McDonough To: docs at lists.fedoraproject.org Subject: Re: Code Examples in Documents Date: Sun, 21 Jun 2015 14:42:06 -0400 Message-ID: <1434912126.16507.65.camel@Aidan> In-Reply-To: dbe47e29ac3852e64eac097f1847c00d@www.eccnet.com --===============8934202832634129517== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable But now your tag won't work. Seems like a step backward to me. On Sun, 2015-06-21 at 13:59 -0400, Betty Harvey wrote: > You can put code into the XML document by using CDATA sections. = > Anything in a CDATA section is ignored by the parser so you can put = > characters that you normally cannot add to an XML document, i.e., less = > than, greater than, etc. > = > Below is how a CDATA section is constructed for the Docbook example = > element: > = > > My Code > > = >

CDATA Section

> = >

Anything in a CDATA section is ignored by the XML Parser.

> ]]> >
>
> = > = > The parser will also respect any white space in the CDATA section so = > what you see will be what you get inside the section. > = > Hope this helps! > = > Betty > = > On 2015-06-21 12:16, David Ashley wrote: > > All - > > = > > In the past when creating a new document that will contain code > > examples in C/C++ or Python I always placed the examples in separate > > files from the main XML. This way it would be easier to test those > > examples to make sure that they work as intended. Being new to the > > Fedora Docs team I have looked at some of the current documents and > > they do not seem to separate the code from the document itself. So I > > am wondering if I should follow that convention or separate the code > > from the XML like I have done in the past? > > = > > Please provide some guidance. > > = > > David Ashley > = > -- = > /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/ > Betty Harvey | Phone: 410-787-9200 FAX: 9830 > Electronic Commerce Connection, Inc. | > harvey(a)eccnet.com | Washington,DC XML Users Grp > URL: http://www.eccnet.com | http://www.eccnet.com/xmlug > /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\\/\/ > Member of XML Guild (www.xmlguild.org) --===============8934202832634129517==-- From harvey at eccnet.com Mon Jun 22 10:17:57 2015 Content-Type: multipart/mixed; boundary="===============1187033287765673236==" MIME-Version: 1.0 From: Betty Harvey To: docs at lists.fedoraproject.org Subject: Re: Code Examples in Documents Date: Sun, 21 Jun 2015 16:32:54 -0400 Message-ID: <51e3678a48602f71a315ab74de49870a@www.eccnet.com> In-Reply-To: 1434912126.16507.65.camel@Aidan --===============1187033287765673236== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable You can use the CDATA construct with the element: CDATA Section

Anything in a CDATA section is ignored by the XML Parser.

]]>
A CDATA section can go anywhere in the document, except in the prolog = and you are still required to have a well-formed XML document. Betty On 2015-06-21 14:42, John J. McDonough wrote: > But now your tag won't work. Seems like a step backward to me. > = > On Sun, 2015-06-21 at 13:59 -0400, Betty Harvey wrote: >> You can put code into the XML document by using CDATA sections. >> Anything in a CDATA section is ignored by the parser so you can put >> characters that you normally cannot add to an XML document, i.e., less >> than, greater than, etc. >> = >> Below is how a CDATA section is constructed for the Docbook example >> element: >> = >> >> My Code >> >> > = >>

CDATA Section

>> = >>

Anything in a CDATA section is ignored by the XML Parser.

>> ]]> >>
>>
>> = >> = >> The parser will also respect any white space in the CDATA section so >> what you see will be what you get inside the section. >> = >> Hope this helps! >> = >> Betty >> = >> On 2015-06-21 12:16, David Ashley wrote: >> > All - >> > >> > In the past when creating a new document that will contain code >> > examples in C/C++ or Python I always placed the examples in separate >> > files from the main XML. This way it would be easier to test those >> > examples to make sure that they work as intended. Being new to the >> > Fedora Docs team I have looked at some of the current documents and >> > they do not seem to separate the code from the document itself. So I >> > am wondering if I should follow that convention or separate the code >> > from the XML like I have done in the past? >> > >> > Please provide some guidance. >> > >> > David Ashley >> = >> -- >> /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/ >> Betty Harvey | Phone: 410-787-9200 FAX: 9830 >> Electronic Commerce Connection, Inc. | >> harvey(a)eccnet.com | Washington,DC XML Users Grp >> URL: http://www.eccnet.com | http://www.eccnet.com/xmlug >> /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\\/\/ >> Member of XML Guild (www.xmlguild.org) -- = /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/ Betty Harvey | Phone: 410-787-9200 FAX: 9830 Electronic Commerce Connection, Inc. | harvey(a)eccnet.com | Washington,DC XML Users Grp URL: http://www.eccnet.com | http://www.eccnet.com/xmlug /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\\/\/ Member of XML Guild (www.xmlguild.org) --===============1187033287765673236==-- From jfearn at redhat.com Mon Jun 22 10:17:57 2015 Content-Type: multipart/mixed; boundary="===============5608925676868649627==" MIME-Version: 1.0 From: Jeff Fearn To: docs at lists.fedoraproject.org Subject: Re: Code Examples in Documents Date: Mon, 22 Jun 2015 09:10:34 +1000 Message-ID: <5587446A.6020606@redhat.com> In-Reply-To: 5586E36E.1030508@gmail.com --===============5608925676868649627== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On 06/22/2015 02:16 AM, David Ashley wrote: > All - > = > In the past when creating a new document that will contain code examples > in C/C++ or Python I always placed the examples in separate files from > the main XML. This way it would be easier to test those examples to make > sure that they work as intended. Being new to the Fedora Docs team I > have looked at some of the current documents and they do not seem to > separate the code from the document itself. So I am wondering if I > should follow that convention or separate the code from the XML like I > have done in the past? IMHO you are doing it the right way. https://jfearn.fedorapeople.org/en-US/Publican/4.3/html/Users_Guide/sect-Pu= blican-Users_Guide-Adding_code_samples.html The trick is to ensure, as per step 3, that your xi:include of the file uses 'parse=3D"text"' so that special characters in your code and handled properly. Cheers, Jeff. --===============5608925676868649627==-- From jfearn at redhat.com Mon Jun 22 10:17:57 2015 Content-Type: multipart/mixed; boundary="===============5739810351137480981==" MIME-Version: 1.0 From: Jeff Fearn To: docs at lists.fedoraproject.org Subject: Re: Code Examples in Documents Date: Mon, 22 Jun 2015 09:13:39 +1000 Message-ID: <55874523.7090403@redhat.com> In-Reply-To: 5587446A.6020606@redhat.com --===============5739810351137480981== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On 06/22/2015 09:10 AM, Jeff Fearn wrote: > On 06/22/2015 02:16 AM, David Ashley wrote: >> All - >> >> In the past when creating a new document that will contain code examples >> in C/C++ or Python I always placed the examples in separate files from >> the main XML. This way it would be easier to test those examples to make >> sure that they work as intended. Being new to the Fedora Docs team I >> have looked at some of the current documents and they do not seem to >> separate the code from the document itself. So I am wondering if I >> should follow that convention or separate the code from the XML like I >> have done in the past? > = > IMHO you are doing it the right way. > = > https://jfearn.fedorapeople.org/en-US/Publican/4.3/html/Users_Guide/sect-= Publican-Users_Guide-Adding_code_samples.html > = > The trick is to ensure, as per step 3, that your xi:include of the file > uses 'parse=3D"text"' so that special characters in your code and handled > properly. Oh also annoy people to start using DocBook5 and Publican 4.3 so you can play with code switchers [1] and poppers [2] :D Cheers, Jeff. 1: https://jfearn.fedorapeople.org/en-US/Publican/4.3/html/Users_Guide/pref-Pu= blican-Users_Guide-Introduction.html#BZ1092351 2: https://jfearn.fedorapeople.org/en-US/Publican/4.3/html/Users_Guide/pref-Pu= blican-Users_Guide-Introduction.html#BZ1088051 --===============5739810351137480981==-- From wb8rcr at arrl.net Mon Jun 22 10:17:58 2015 Content-Type: multipart/mixed; boundary="===============6011043937222863972==" MIME-Version: 1.0 From: John J. McDonough To: docs at lists.fedoraproject.org Subject: Re: Code Examples in Documents Date: Sun, 21 Jun 2015 20:05:50 -0400 Message-ID: <1434931550.16507.74.camel@Aidan> In-Reply-To: 5587446A.6020606@redhat.com --===============6011043937222863972== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable AHA The secret I overlooked is that the code fragment needs to be in a different directory. The error message is kind of misleading, took a bit of head scratching. My knee-jerk would probably have been to put the code in its own directory anyway, but when you are throwing together a quick test ... OK, so that works pretty well, and in response to David's suggestion, it looks like a real good one. --McD On Mon, 2015-06-22 at 09:10 +1000, Jeff Fearn wrote: > On 06/22/2015 02:16 AM, David Ashley wrote: > > All - > > = > > In the past when creating a new document that will contain code examples > > in C/C++ or Python I always placed the examples in separate files from > > the main XML. This way it would be easier to test those examples to make > > sure that they work as intended. Being new to the Fedora Docs team I > > have looked at some of the current documents and they do not seem to > > separate the code from the document itself. So I am wondering if I > > should follow that convention or separate the code from the XML like I > > have done in the past? > = > IMHO you are doing it the right way. > = > https://jfearn.fedorapeople.org/en-US/Publican/4.3/html/Users_Guide/sect-= Publican-Users_Guide-Adding_code_samples.html > = > The trick is to ensure, as per step 3, that your xi:include of the file > uses 'parse=3D"text"' so that special characters in your code and handled > properly. > = > Cheers, Jeff. --===============6011043937222863972==--