LLVM documentation work help

Sean,

I am happy to introduce Anoushe, my llvm backend documentation work helper for English and edit.

Is it possible, me and Anoushe can get a git free space and access right for the reStructuredText files (include .png pictures) of me and Anoushe create in future? If not allowed. Can we hand over the reStructuredText files, and put to git server through you?

Best regards

Jonathan

I am happy to introduce Anoushe, my llvm backend documentation work helper for English and edit.

Awesome! Great to see people helping out. Thank you both for working on this.

Is it possible, me and Anoushe can get a git free space and access right for the reStructuredText files (include .png pictures) of me and Anoushe create in future? If not allowed. Can we hand over the reStructuredText files, and put to git server through you?

I would suggest that you create a git repository on github. LLVM
itself does not have any git servers except for hosting the SVN
mirror.

If you want, I can setup a git repository and give you access if you
think it would be easier that way. Just tell me what seems easiest for
you.

-- Sean Silva

Sean,

By try, I seems realize the github.com is free for register. So, just ignore my last mail.

Anoushe,

You can register with email and get an account on
https://github.com/

I have put the our document reStructuredText on git.hub.com. You can clone it without register.
After you get an account and I add it to collaborators, then you can do check in with our project as follows,

https://github.com/Jonathan2251/lbd.git

Jonathan

It looks like things are going well.

One suggestion. Instead of using `.. literalinclude::` for displaying
the terminal sessions, you can use `.. code-block:: bash` instead. The
reason that uvbook uses `.. literalinclude` is that they are showing
parts of real compilable programs. If you just want to show a snippet
of code or terminal snippet, you can use `.. code-block::` and avoid
having lots of little files.

-- Sean Silva

Sean,

The `.. code-block:: bash` is work. Thank your information.

Currently, I can put reStructuredText files on github. But, your example uvbook seems put the html and pdf on different github directory. Do you put html and pdf on github with version control?

Jonathan

Let me explain how uvbook does it. They use a feature of github called
"github pages", which provides small static website hosting. The way
that github pages works is that you make a git branch `gh-pages` which
contains the generated HTML. They explain it better here
<https://help.github.com/articles/creating-project-pages-manually>.
You can see how uvbook does it by looking at their makefile
<https://github.com/nikhilm/uvbook/blob/master/Makefile#L160>. It
should be easy to reuse.

I think that you should do this so that it is easy for anyone to read
the book without leaving their browser. That will mean that more
people read it and contribute.

-- Sean Silva

The author of uvbook also has a blog post about setting up github
pages <http://blog.nikhilism.com/2012/08/automatic-github-pages-generation-from.html>.

-- Sean Silva

Sean,

I can create html, pdf and epub, then put them on
<https://github.com/Jonathan2251/lbd/tree/gh-pages>.
The uvbook example as below can click the pdf link and pop up a download window while I cannot. The uvbook link is put on http://username.github.com/… while the “make gh-pages” put them on https://github.com/username/… How can I have the download link like uvbook example?

A really good example of a book written with Sphinx is <https://github.com/nikhilm/uvbook>. Sphinx can then generate HTML <http://nikhilm.github.com/uvbook/index.html> or PDF <http://nikhilm.github.com/uvbook/An%20Introduction%20to%20libuv.pdf>



My steps as follows,
1. I follow your one time procedure as follows,
<https://help.github.com/articles/creating-project-pages-manually>.
2. make gh-pages (I modify file Makefile for my document name before do this)

Jonathan


12/12/3 (一),Sean Silva silvas@purdue.edu 寫道:


> 寄件者: Sean Silva silvas@purdue.edu
> 主旨: Re: LLVM documentation work help
> 收件者: “Jonathan” gamma_chen@yahoo.com.tw
> 副本: “llvmdev@cs.uiuc.edu” llvmdev@cs.uiuc.edu, “Anoushe Jamshidi” ajamshidi@gmail.com
> 日期: 2012年12月3日,一,下午2:48
>
> Let me explain how uvbook does it. They use a feature of github called
> “github pages”, which provides small static website hosting. The way
> that github pages works is that you make a git branch gh-pages which
> contains the generated HTML. They explain it better here
> <https://help.github.com/articles/creating-project-pages-manually>.
> You can see how uvbook does it by looking at their makefile
> <https://github.com/nikhilm/uvbook/blob/master/Makefile#L160>. It
> should be easy to reuse.
>
> I think that you should do this so that it is easy for anyone to read
> the book without leaving their browser. That will mean that more
> people read it and contribute.
>
> – Sean Silva
>
> On Sun, Dec 2, 2012 at 11:03 PM, Jonathan gamma_chen@yahoo.com.tw wrote:
> > Sean,
> >
> > The .. code-block:: bash is work. Thank your information.
> >
> > Currently, I can put reStructuredText files on github. But, your example uvbook seems put the html and pdf on different github directory. Do you put html and pdf on github with version control?
> >
> > Jonathan
> >
> >
> > On 2012/12/3, at 上午7:43, Sean Silva silvas@purdue.edu wrote:
> >
> >> It looks like things are going well.
> >>
> >> One suggestion. Instead of using .. literalinclude:: for displaying
> >> the terminal sessions, you can use .. code-block:: bash instead. The
> >> reason that uvbook uses .. literalinclude is that they are showing
> >> parts of real compilable programs. If you just want to show a snippet
> >> of code or terminal snippet, you can use .. code-block:: and avoid
> >> having lots of little files.
> >>
> >> – Sean Silva
> >>
> >> On Thu, Nov 29, 2012 at 10:43 AM, Jonathan gamma_chen@yahoo.com.tw wrote:
> >>> Sean,
> >>>
> >>> By try, I seems realize the github.com is free for register. So, just ignore my last mail.
> >>>
> >>> Anoushe,
> >>>
> >>> You can register with email and get an account on
> >>> https://github.com/
> >>>
> >>> I have put the our document reStructuredText on git.hub.com. You can clone it without register.
> >>> After you get an account and I add it to collaborators, then you can do check in with our project as follows,
> >>>
> >>> https://github.com/Jonathan2251/lbd.git
> >>>
> >>> Jonathan
> >>>
> >>> On 2012/11/29, at 下午7:13, Sean Silva silvas@purdue.edu wrote:
> >>>
> >>>>> I am happy to introduce Anoushe, my llvm backend documentation work helper for English and edit.
> >>>>
> >>>> Awesome! Great to see people helping out. Thank you both for working on this.
> >>>>
> >>>>> Is it possible, me and Anoushe can get a git free space and access right for the reStructuredText files (include .png pictures) of me and Anoushe create in future? If not allowed. Can we hand over the reStructuredText files, and put to git server through you?
> >>>>
> >>>> I would suggest that you create a git repository on github. LLVM
> >>>> itself does not have any git servers except for hosting the SVN
> >>>> mirror.
> >>>>
> >>>> If you want, I can setup a git repository and give you access if you
> >>>> think it would be easier that way. Just tell me what seems easiest for
> >>>> you.
> >>>>
> >>>> – Sean Silva
> >>>
> >

|

You may need a “.nojekyll” file. uvbook has one <https://github.com/nikhilm/uvbook/blob/gh-pages/.nojekyll>. Also see <https://help.github.com/articles/files-that-start-with-an-underscore-are-missing>.

Let me know if that doesn’t work.

– Sean Silva

Hi Jonathan,

  sorry for the hijack. Can I help you writing the document?

Regards,
chenwj

Sean,

I add the empty file .nojekyll to https://github.com/Jonathan2251/lbd/tree/gh-pages and do “make gh-pages” again. It’s the same. I check the uvbook has the gh-pages as mine as follows,

https://github.com/nikhilm/uvbook/tree/gh-pages
https://github.com/Jonathan2251/lbd/tree/gh-pages

In addition to gh-pages, uvbook has the the other web site on
http://nikhilm.github.com/uvbook/

I think, maybe the extra web site is created manually and copy the gh-pages to it. Or the extra http site (not https) is created automatically. Because I cannot see it put html to the extra web from gh-pages of Makefile.

Jonathan

12/12/4 (二),Sean Silva silvas@purdue.edu 寫道:

Wei-Ren,

Sorry, currently, I have an English helper in documentation. The cpu0 is my brother teaching material for college, and I did llvm backend compiler tutorial for cpu0 since I didn’t find a good tutorial in llvm backend design.

As I know, there are many way to contribute back to open source or llvm. For example, write qemu for cpu0 is a extended work in cpu0 llvm backend design. Or write program in llvm Mips backend to allow it run on Mips qemu environment (I don’t know if there is a way to run the Mips backend code on X86 platform through qemu). Or you can start with a very different CPU, like DSP processor, as llvm backend design. I think, there are peoples interested with this.

Actually, I am jobless at home. I do this work for career and try to find a compiler pay job. I don’t know your situation. Anything as above I mentioned need a lot of time to work. You can discuss with me first. I will pass the information to Sean when you choose a topic.

Best regards

Jonathan

12/12/4 (二),陳韋任 (Wei-Ren Chen) chenwj@iis.sinica.edu.tw 寫道:


> 寄件者: 陳韋任 (Wei-Ren Chen) chenwj@iis.sinica.edu.tw
> 主旨: Re: [LLVMdev] LLVM documentation work help
> 收件者: “gamma_chen” gamma_chen@yahoo.com.tw
> 副本: “Sean Silva” silvas@purdue.edu, “llvmdev@cs.uiuc.edu” llvmdev@cs.uiuc.edu
> 日期: 2012年12月4日,二,上午11:39
>
> Hi Jonathan,
>
> sorry for the hijack. Can I help you writing the document?
>
> Regards,
> chenwj
>
> On Tue, Dec 04, 2012 at 10:15:33AM +0800, gamma_chen wrote:
> > Sean,
> >
> > I can create html, pdf and epub, then put them on
> > <https://github.com/Jonathan2251/lbd/tree/gh-pages>.
> > The uvbook example as below can click the pdf link and pop up a download window
> > while I cannot. The uvbook link is put on http://username.github.com/… while
> > the “make gh-pages” put them on https://github.com/username/… How can I have
> > the download link like uvbook example?
> >
> > A really good example of a book written with Sphinx is <https://github.com/
> > nikhilm/uvbook>. Sphinx can then generate HTML <http://nikhilm.github.com/
> > uvbook/index.html> or PDF <http://nikhilm.github.com/uvbook/
> > An%20Introduction%20to%20libuv.pdf>
> >
> >
> >
> > My steps as follows,
> > 1. I follow your one time procedure as follows,
> > <https://help.github.com/articles/creating-project-pages-manually>.
> > 2. make gh-pages (I modify file Makefile for my document name before do this)
> >
> > Jonathan
> >
> >
> > — 12/12/3 (一),Sean Silva silvas@purdue.edu 寫道:
> >
> >
> > 寄件者: Sean Silva silvas@purdue.edu
> > 主旨: Re: LLVM documentation work help
> > 收件者: “Jonathan” gamma_chen@yahoo.com.tw
> > 副本: “llvmdev@cs.uiuc.edu” llvmdev@cs.uiuc.edu, “Anoushe Jamshidi”
> > ajamshidi@gmail.com
> > 日期: 2012年12月3日,一,下午2:48
> >
> > Let me explain how uvbook does it. They use a feature of github called
> > “github pages”, which provides small static website hosting. The way
> > that github pages works is that you make a git branch gh-pages which
> > contains the generated HTML. They explain it better here
> > <https://help.github.com/articles/creating-project-pages-manually>.
> > You can see how uvbook does it by looking at their makefile
> > <https://github.com/nikhilm/uvbook/blob/master/Makefile#L160>. It
> > should be easy to reuse.
> >
> > I think that you should do this so that it is easy for anyone to read
> > the book without leaving their browser. That will mean that more
> > people read it and contribute.
> >
> > – Sean Silva
> >
> > On Sun, Dec 2, 2012 at 11:03 PM, Jonathan gamma_chen@yahoo.com.tw wrote:
> > > Sean,
> > >
> > > The .. code-block:: bash is work. Thank your information.
> > >
> > > Currently, I can put reStructuredText files on github. But, your example
> > uvbook seems put the html and pdf on different github directory. Do you put
> > html and pdf on github with version control?
> > >
> > > Jonathan
> > >
> > >
> > > On 2012/12/3, at 上午7:43, Sean Silva silvas@purdue.edu wrote:
> > >
> > >> It looks like things are going well.
> > >>
> > >> One suggestion. Instead of using .. literalinclude:: for displaying
> > >> the terminal sessions, you can use .. code-block:: bash instead. The
> > >> reason that uvbook uses .. literalinclude is that they are showing
> > >> parts of real compilable programs. If you just want to show a snippet
> > >> of code or terminal snippet, you can use .. code-block:: and avoid
> > >> having lots of little files.
> > >>
> > >> – Sean Silva
> > >>
> > >> On Thu, Nov 29, 2012 at 10:43 AM, Jonathan gamma_chen@yahoo.com.tw
> > wrote:
> > >>> Sean,
> > >>>
> > >>> By try, I seems realize the github.com is free for register. So, just
> > ignore my last mail.
> > >>>
> > >>> Anoushe,
> > >>>
> > >>> You can register with email and get an account on
> > >>> https://github.com/
> > >>>
> > >>> I have put the our document reStructuredText on git.hub.com. You can
> > clone it without register.
> > >>> After you get an account and I add it to collaborators, then you can do
> > check in with our project as follows,
> > >>>
> > >>> https://github.com/Jonathan2251/lbd.git
> > >>>
> > >>> Jonathan
> > >>>
> > >>> On 2012/11/29, at 下午7:13, Sean Silva silvas@purdue.edu wrote:
> > >>>
> > >>>>> I am happy to introduce Anoushe, my llvm backend documentation work
> > helper for English and edit.
> > >>>>
> > >>>> Awesome! Great to see people helping out. Thank you both for working
> > on this.
> > >>>>
> > >>>>> Is it possible, me and Anoushe can get a git free space and access
> > right for the reStructuredText files (include .png pictures) of me and
> > Anoushe create in future? If not allowed. Can we hand over the
> > reStructuredText files, and put to git server through you?
> > >>>>
> > >>>> I would suggest that you create a git repository on github. LLVM
> > >>>> itself does not have any git servers except for hosting the SVN
> > >>>> mirror.
> > >>>>
> > >>>> If you want, I can setup a git repository and give you access if you
> > >>>> think it would be easier that way. Just tell me what seems easiest for
> > >>>> you.
> > >>>>
> > >>>> – Sean Silva
> > >>>
> > >
> >
>
> > _______________________________________________
> > LLVM Developers mailing list
> > LLVMdev@cs.uiuc.edu http://llvm.cs.uiuc.edu
> > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>
> –
> Wei-Ren Chen (陳韋任)
> Computer Systems Lab, Institute of Information Science,
> Academia Sinica, Taiwan (R.O.C.)
> Tel:886-2-2788-3799 #1667
> Homepage: http://people.cs.nctu.edu.tw/~chenwj

|

The book looks really good at <http://jonathan2251.github.com/lbd/>!

I think if you change the PDF link to
<http://jonathan2251.github.com/lbd/WriteAnLLVMBackendTutorialForCpu0.pdf>
it will work.

-- Sean Silva

It's available on github <https://github.com/Jonathan2251/lbd> :wink: Just
send a pull request.

However, before going and sending a pull request, maybe you could
discuss what you want to contribute to the book. For example, what
parts of the codebase do you know a lot about? Or maybe you just want
to help with formatting?

-- Sean Silva

Sorry, currently, I have an English helper in documentation. The cpu0 is my brother teaching material for college, and I did llvm backend compiler tutorial for cpu0 since I didn't find a good tutorial in llvm backend design.

Maybe I misunderstood, but are you saying that you do not want help? I
think that you should try to encourage as many people to contribute as
possible; that is how open source works best. You started it so your
name will be on the cover though :wink:

-- Sean Silva

Sean,

It is not work even though I change the PDF link as you indicated. I think I can just use directory/link https://github.com/Jonathan2251/lbd/tree/gh-pages instead http://jonathan2251.github.com/lbd/WriteAnLLVMBackendTutorialForCpu0.pdf as a work around solution. User can click the link and click left top button “ZIP” and get the epub and pdf.

Jonathan

12/12/4 (二),Sean Silva silvas@purdue.edu 寫道:


> 寄件者: Sean Silva silvas@purdue.edu
> 主旨: Re: LLVM documentation work help
> 收件者: “gamma_chen” gamma_chen@yahoo.com.tw
> 副本: “llvmdev@cs.uiuc.edu” llvmdev@cs.uiuc.edu, “Anoushe Jamshidi” ajamshidi@gmail.com
> 日期: 2012年12月4日,二,下午12:45
>
> On Mon, Dec 3, 2012 at 11:09 PM, gamma_chen gamma_chen@yahoo.com.tw wrote:
> > I add the empty file .nojekyll to https://github.com/Jonathan2251/lbd/tree/gh-pages and do “make gh-pages” again. It’s the same. I check the uvbook has the gh-pages as mine as follows,
>
> The book looks really good at <http://jonathan2251.github.com/lbd/>!
>
> I think if you change the PDF link to
> <http://jonathan2251.github.com/lbd/WriteAnLLVMBackendTutorialForCpu0.pdf>
> it will work.
>
> – Sean Silva

|

It is not work even though I change the PDF link as you indicated. I think I can just use directory/link https://github.com/Jonathan2251/lbd/tree/gh-pages instead http://jonathan2251.github.com/lbd/WriteAnLLVMBackendTutorialForCpu0.pdf as a work around solution. User can click the link and click left top button "ZIP" and get the epub and pdf.

<http://jonathan2251.github.com/lbd/WriteAnLLVMBackendTutorialForCpu0.pdf>
works for me. Why did you change it?

-- Sean Silva

All,

With Sean help, I finish the gh-pages setting and our book’s home page will display on the following site. It will update automatically by “make gh-pages”.

http://jonathan2251.github.com/lbd/index.html

Click left bottom button PDF or ePub can pop up a download window. This setting is in source/index.rst, so I don’t write down the setting about this.

Sean, thank your help.

iMac sphinx setting is finished last night and the gh-pages release setting is fixed this morning. Suppose should take a walk outside, but it’s raining in Taipei …

Jonathan