Code Examples in Documents

[John J. McDonough]

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 <code> or <screen> 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