TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
On Fri, Feb 20, 2015 at 5:03 AM, Mark Giffin <mgiffin -at- earthlink -dot- net> wrote:
> I'm fairly sure that you can use Sphinx with programming languages other
> than Python. Or even without a programming language. If you're interested
> in Sphinx I suggest you check this out.
>
> Mark Giffin
> Mark Giffin Consulting, Inc.
>http://markgiffin.com/
>
> On 2/19/2015 6:50 PM, Ryan Young wrote:
>
>> Sphinx sounds pretty great, Elisa. Your situation sounds similar to mine,
>> where you're working very closely with the developers. I don't work with
>> any Python guys (that I know of), but they'd probably like
>> ReStructuredText.
>>
>> Thank you and everyone else on this thread for your suggestions. Much
>> appreciated.
>>
>> On Thu, Feb 19, 2015 at 11:00 AM, Elisa R. Sawyer <elisawyer -at- gmail -dot- com>
>> wrote:
>>
>> Hi Ryan,
>>>
>>> You've already gotten a few good suggestions, and I have one add to the
>>> list.
>>>
>>> Markdown is by design simple and therefore limited. LaTeX allows for
>>> precise formatting, but it might be difficult to get your build to create
>>> pdf's of the quality you want using Markdown. Moving toward Docbook is
>>> one
>>> possibility, but there is another, somewhat more developer-friendly
>>> solution--ReStructuredText using Sphinx, which can be considered a
>>> slightly
>>> more grown-up version of Markdown:
>>>
>>> You can find information on several Web sites:
>>>
>>> http://sphinx-doc.org/contents.html
>>> http://docutils.sourceforge.net/rst.html
>>> http://pedrokroger.net/using-sphinx-write-technical-books/
>>>
>>> To get a pdf from Sphinx you need to install a pdflatex plugin. The
>>> details of what you need vary with operating system.
>>>
>>> I inherited a set of docs that were created using Sphinx and had to find
>>> my way around the process of editing in .rst files and building both HTML
>>> and pdf output. I'm using Sublime Text with several plugins, on a Mac
>>> with
>>> OS X Yosemite. I'm still learning some of the finer points but think that
>>> this has a lot of potential.
>>>
>>> In my case, I discovered that I can get some developer input when I hit a
>>> road block with a specific issue, which makes the process fun and
>>> interesting. This happens because Sphinx is seen as a tool for python
>>> developers. I don't think that it's any more difficult to tweak the build
>>> for good pdf's from this setup than it is to tweak DITA-OT or Docbook.
>>>
>>> -Elisa
>>>
>>>
>>>
>>> On Wed, Feb 18, 2015 at 8:56 PM, Ryan Young <ryangyoung -at- gmail -dot- com>
>>> wrote:
>>>
>>> Hello,
>>>>
>>>> At my new job, what documentation there is is in Markdown. The engineers
>>>> set up a script using pandoc to create some functional PDF output. The
>>>> problem is that pandoc requires LaTex to produce the PDF, which doesn't
>>>> give me very much control of things like the location of images in the
>>>> document (or the ability to create links).
>>>>
>>>> I've played around with Atom and SublimeText, but neither gives me all
>>>> that
>>>> much more control over the PDF output. I've also suggested the company
>>>> start using Confluence, which would solve the problem, but it seems like
>>>> that will take a bit of planning.
>>>>
>>>> Any suggestions?
>>>> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>>> Doc-To-Help: The Quickest Way to Author and Publish Online Help, Policy
>>>> &
>>>> Procedure Guides, eBooks, and more using Microsoft Word |
>>>> http://bit.ly/doctohelp2015
>>>>
>>>> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>>>
>>>> You are currently subscribed to TECHWR-L as elisawyer -at- gmail -dot- com -dot-
>>>>
>>>> To unsubscribe send a blank email to
>>>> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>>>>
>>>>
>>>> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>>>> http://www.techwhirl.com/email-discussion-groups/ for more resources
>>>> and
>>>> info.
>>>>
>>>> Looking for articles on Technical Communications? Head over to our
>>>> online magazine at http://techwhirl.com
>>>>
>>>> Looking for the archived Techwr-l email discussions? Search our public
>>>> email archives @ http://techwr-l.com/archives
>>>>
>>>>
>>>
>>> --
>>> Elisa Rood Sawyer
>>> ~~~~~^~~~~~
>>> Technical and Creative Writer
>>> "Apparently there is nothing that cannot happen today." Mark Twain
>>>
>>>
>>>
>>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Doc-To-Help: The Quickest Way to Author and Publish Online Help, Policy &
> Procedure Guides, eBooks, and more using Microsoft Word |
>http://bit.ly/doctohelp2015
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as serdar -dot- a -dot- ozmen -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Doc-To-Help: The Quickest Way to Author and Publish Online Help, Policy & Procedure Guides, eBooks, and more using Microsoft Word | http://bit.ly/doctohelp2015
