[Swift-devel] Website documentation

[David Kelly]

Hello,

I created a first draft of the Swift tutorial in asciidoc. Here are the
documents it created:

HTML: http://www.ci.uchicago.edu/~davidk/tutorial.html
PDF: http://www.ci.uchicago.edu/~davidk/tutorial.pdf
ASCIIDOC: http://www.ci.uchicago.edu/~davidk/tutorial.txt

There are still a few things I need to tweak, but overall I'm finding
asciidoc pretty nice to work with.

The ticket that was created for this, 375, mentions that these documents
should be created during ant dist. But I think most people do not have
asciidoc installed by default, and including it with Swift will not be
possible due to GPL licensing issues. Asciidoc itself is GPL, as well as the
various packages it depends on - source-highlight for code highlighting, and
dblatex for generating PDFs.

I think Justin's suggestion of keeping document generation limited to a CI
machine is the way to go. If that makes sense to you all, I will start on a
script to generate the documents, and continue working on manually
converting the rest of the documentation material into asciidoc format.

David

On Sat, Apr 23, 2011 at 1:00 PM, Justin M Wozniak <wozniak at mcs.anl.gov>wrote:

>
> Yeah- I am trying to be more careful with umask.  Please send me your error
> message and I will modify the chmods in the script accordingly.
>
> For the new structure, I recommend that we stop using svn to move the
> content and just push the simple documents.  I would be fine with a cp-based
> method that only works from a CI system.
>
>
> On Sat, 23 Apr 2011, Michael Wilde wrote:
>
>  Looking deeper into this, I see that the permissions in /ci
>> /www/projects/swift do not permit anyone in vdl2-svn to do svn-update and to
>> run update.sh completely for the entire doc set.
>>
>>
>> Justin, I think this occurred when you last worked on this directory. Can
>> you see if update.sh works for you at the moment? That should push David's
>> committed tutorial corrections to the live content.
>>
>>
>> I suggest that rather than correct this, we push ahead updating the entire
>> per-release doc set to asciidoc and then adjust update.sh and the
>> /ci/www/projects/swift directory to match it. David, can you do this under
>> bug 375, and propose the new structure with a README that outlines how all
>> the directories and content-push scripts will be organized?
>>
>>
>> Thanks,
>>
>>
>> Mike
>>
>>
>> ----- Original Message -----
>>
>>
>>
>> David, you're not in the vdl2-svn UNIX group, which you need in order to
>> run this. I'll request that you be added, and do an svn-co of the tutorial
>> and run update.sh for you in the meantime.
>>
>>
>> - Mike
>>
>> ----- Original Message -----
>>
>>
>> Hello,
>>
>>
>> What is the current process for updating website documentation? I believe
>> the MaintainingSwiftWebContent wiki may be out of date.
>>
>>
>> I am trying to submit some corrections to the Swift tutorial. Previously I
>> could modify it through www/ in SVN. Now I believe it is generated from
>> swift/docs/tutorial.xml for each release. Is this correct? Is there still a
>> cron job that runs daily and updates the site? I am not seeing the changes I
>> made yesterday reflected on the website. Do I need to manually run
>> /ci/www/projects/swift/update.sh? I do not have permissions to read or
>> execute it at the moment.
>>
>>
>> Thanks,
>> David
>>
>>
>> _______________________________________________
>> Swift-devel mailing list
>> Swift-devel at ci.uchicago.edu
>> http://mail.ci.uchicago.edu/mailman/listinfo/swift-devel
>>
>>
>>
>>
>>
> --
> Justin M Wozniak
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/swift-devel/attachments/20110425/c009311f/attachment.html>