Re: markdown 2 man, was Re: Git Community Book

15 messages
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 Hello, Sorry for this irruption on this list. I am just a git user and casual reader of this list. I thought I could share my thoughts about this as I know a bit about document creation. Please ignore if this is not appropriate. Disclaimer: I am involved in LyX development, so anything I said will be biased :-) Junio C Hamano wrote: > As I am not in "graphics and screencast" camp, I may probably not be able > to offer much help improving his book, and I suspect some people on this > list might feel the same way.  But that's is Ok --- we are not dumping the > User Manual. IMHO, documentation is best written by users, not developer. So, again IMHO, anything that could accommodate the _user_ for document writing should be done. An enthusiastic user is more likely to spend time writing documentation than a developer. For example, within the LyX project, most writers and translator are not developer. Asciidoc or Markdown are tools that accommodate the _developer_, not the user. I understand that these markup language are ideally suited for in source documentation (thought I personally much prefer Doxygen). I also understand that launching a different application just to modify a line or two in the user manual seems cumbersome for the developer but IMHO, if you're serious about working on the documentation, you are not going to change a line or two and launching an external application is no big deal. Now, about my shameless plug: LyX is ideally suited for structured documentation writing :-) Abdel. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 Hi, Abdelrazak Younes wrote: > Please ignore if this is not appropriate. Well, so I should've ignored, but I think this is worth some correction. > Asciidoc or Markdown are tools that accommodate the _developer_, not the   > user. I understand that these markup language are ideally suited for in   > source documentation (thought I personally much prefer Doxygen). http://www.methods.co.nz/asciidoc/ says  AsciiDoc is a text document format for writing short documents,    articles, books and UNIX man pages. AsciiDoc files can be translated to    HTML and DocBook markups using the asciidoc(1) command.'' http://daringfireball.net/projects/markdown/ says  Markdown is a text-to-HTML conversion tool for web writers. Markdown    allows you to write using an easy-to-read, easy-to-write plain text    format, then convert it to structurally valid XHTML (or HTML).'' So those are not suited for in-source documentation. They're "lightweight" markup for documentation, very easy to read and somehow easy to write for non-developers. The user manual can give you an impression:         http://repo.or.cz/w/git.git?a=blob;f=Documentation/user-manual.txtI think, this is easier than LyX for users and developers.. Regards,   Stephan -- Stephan Beyer <[hidden email]>, PGP 0x6EDDD207FCC5040F -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 Stephan Beyer wrote: > Hi, > > Abdelrazak Younes wrote: >     >> Please ignore if this is not appropriate. >>       > > Well, so I should've ignored, but I think this is worth some correction. >     Thanks for the corrections :-) > They're "lightweight" markup for documentation, very easy to read and somehow > easy to write for non-developers. > The user manual can give you an impression: > http://repo.or.cz/w/git.git?a=blob;f=Documentation/user-manual.txt> > I think, this is easier than LyX for users and developers.. >     Well, easier for short document writing maybe, better suited I don't think so, at least if you want to keep track of contents, structure, links, references, citations, etc. Bug again this is IMHO. Abdel. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 In reply to this post by Stephan Beyer Stephan Beyer wrote: > They're "lightweight" markup for documentation, very easy to read and somehow > easy to write for non-developers. > The user manual can give you an impression: > http://repo.or.cz/w/git.git?a=blob;f=Documentation/user-manual.txt> > I think, this is easier than LyX for users and developers.. I just had a look at the user manual and, well unless you have a special emacs mode or whatever that can automate the markup tag insertion, I wonder how can anybody think that writing with this markup language is easier than within LyX, really (genuine question, not sarcasm). Abdel. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 On Thu, Jul 31, 2008 at 04:33:24PM +0200, Abdelrazak Younes <[hidden email]> wrote: > I just had a look at the user manual and, well unless you have a special > emacs mode or whatever that can automate the markup tag insertion, I wonder > how can anybody think that writing with this markup language is easier than > within LyX, really (genuine question, not sarcasm). People usually find it easy to contribute to a wiki, due to its easy markup language. asciidoc's markup is configurable, but the default one is really similar to a wiki syntax, so at the end, people find it easy, including myself. attachment0 (204 bytes) Download Attachment
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 Hi Miklos, Miklos Vajna wrote: > On Thu, Jul 31, 2008 at 04:33:24PM +0200, Abdelrazak Younes<[hidden email]>  wrote: >     >> I just had a look at the user manual and, well unless you have a special >> emacs mode or whatever that can automate the markup tag insertion, I wonder >> how can anybody think that writing with this markup language is easier than >> within LyX, really (genuine question, not sarcasm). >>       > > People usually find it easy to contribute to a wiki, due to its easy > markup language. >     I understand that but my point is that writing a book or a manual is too big a task for a wiki. Anyway, if there is an interest to switch to LyX for the user manual, just let me know. Ascii has a LateX backend* and LyX can import LateX so the task should be easy. * http://www.methods.co.nz/asciidoc/latex-backend.htmlThanks for answering :-) Abdel. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 On Thu, Jul 31, 2008 at 05:29:13PM +0200, Abdelrazak Younes <[hidden email]> wrote: > I understand that but my point is that writing a book or a manual is too > big a task for a wiki. That's probably subjective. There is http://wikibooks.org/, after all. ;-) > Anyway, if there is an interest to switch to LyX for the user manual, just > let me know. Ascii has a LateX backend* and LyX can import LateX so the > task should be easy. > > * http://www.methods.co.nz/asciidoc/latex-backend.htmlLast time I checked it was actually broken, but dblatex can transform asciidoc's docbook output to latex, if that's really wished. attachment0 (204 bytes) Download Attachment
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 In reply to this post by Abdelrazak Younes-2 Hi, > Disclaimer: I am involved in LyX development, so anything I said will > be biased :-) I think that's fine since I consider LaTeX (and therefore LyX as the best graphical editor for it that I know) a choice always worth considering when it comes to projects that have the size of a book. > Now, about my shameless plug: LyX is ideally suited for structured > documentation writing :-) That may well be, but it gets really complicated once you want to get your document into other markup-based formats while preserving all the important aspects of formatting. I know this because I started using LaTeX for a project that was supposed to be available in HTML form along with, say, PDF. I've found that the only converter that comes close to being useful for somewhat more ambitious sources (including, perhaps, custom environments and stuff like that) without spending a ridiculous amount of time trying to understand it is hevea. Of course, hevea only translates to HTML, so, for example, generating manpages or plain text is an entirely different matter of considerable difficulty. In addition to that, I suspect that LyX files might be difficult to deal with in forky Git situations. For example, what if two separately contributed patches need merging into a LyX source file? This will only work automatically if the LyX source, treated as plain text, has a really low chance of randomly changing in other places than what the patch is supposed to touch. Also, if a merge does cause a conflict, I imagine it would be difficult to resolve that. Finally, it's pretty much a given that Git's manpages continue to use AsciiDoc because there are few other things that can generate actual manpages. I'm not sure it would be a good idea to keep half of Git's documentation in one format and the rest in another. And AsciiDoc is -- by far! -- not the worst choice. I'm tempted to say it's the best that I know. -Jan -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 In reply to this post by Abdelrazak Younes-2 Abdelrazak Younes <[hidden email]> writes: > I just had a look at the user manual and, well unless you have a > special emacs mode or whatever that can automate the markup tag > insertion, I wonder how can anybody think that writing with this > markup language is easier than within LyX, really (genuine question, > not sarcasm). How greppable and "log -p"-able is the documentation written in LyX?  * Where in the documentation do I have to change the description of    "--parents" option?  * When did the description of "--cc" for diff families last changed, by    whom and why? Eas of doing these is mostly why we chose AsciiDoc to begin with.  Any alternative you are going to suggest should not make these two things impossible or very harder to do. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 Junio C Hamano wrote: > Abdelrazak Younes<[hidden email]>  writes: > >     >> I just had a look at the user manual and, well unless you have a >> special emacs mode or whatever that can automate the markup tag >> insertion, I wonder how can anybody think that writing with this >> markup language is easier than within LyX, really (genuine question, >> not sarcasm). >>       > > How greppable and "log -p"-able is the documentation written in LyX? >     LyX format is plain text, loosely based on LateX. Here's attached a sample .lyx file FYI. We have one tag per line and a maximum of 80 char per line so that the format is easily parsable. Advanced users often use unix tools (grep, sed, etc) to modify the .lyx file manually. >   * Where in the documentation do I have to change the description of >     "--parents" option? >     You mean in a text editor, not within LyX? Just look for the string :-) >   * When did the description of "--cc" for diff families last changed, by >     whom and why? >     Ditto. > Eas of doing these is mostly why we chose AsciiDoc to begin with.  Any > alternative you are going to suggest should not make these two things > impossible or very harder to do. >     If you ignore the LyX tags, you can just do what you are used to do without problem using a plain text editor. If you want to do something more complicated stuff like choosing a different environment or creating a nested enumerate list, it is easier to do that within LyX. Abdel. FAQ.lyx (47K) Download Attachment
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 In reply to this post by Jan Krüger Hi Jan, Jan Krüger wrote: >> Now, about my shameless plug: LyX is ideally suited for structured >> documentation writing :-) > > That may well be, but it gets really complicated once you want to > get your document into other markup-based formats while preserving all > the important aspects of formatting. I know this because I started > using LaTeX for a project that was supposed to be available in HTML > form along with, say, PDF. I've found that the only converter that > comes close to being useful for somewhat more ambitious sources > (including, perhaps, custom environments and stuff like that) without > spending a ridiculous amount of time trying to understand it is hevea. I had good success with htlatex (the default converter within LyX). I just modified the css and was done with it. All cross-references etc were correctly handled. > Of course, hevea only translates to HTML, so, for example, generating > manpages or plain text is an entirely different matter of considerable > difficulty. LyX has an excellent plain text export. You can use the export method of LyX at the command line without launching it graphically by the way. You don't even need an X server, just use 'lyx -e text mydocument.lyx' For man page, LyX does not support it natively I'm afraid, but I guess there are LateX to man converter, aren't there? > In addition to that, I suspect that LyX files might be difficult to > deal with in forky Git situations. For example, what if two > separately contributed patches need merging into a LyX source file? > This will only work automatically if the LyX source, treated as plain > text, has a really low chance of randomly changing in other places than > what the patch is supposed to touch. Also, if a merge does cause a > conflict, I imagine it would be difficult to resolve that. Not really. As I said to Junio, .lyx files are using a plain text utf8 format. They are easily mergeable as LyX preserves the structure of the file: if the two collaborators modify two different parts of the document there is basically zero chance to have a conflict. On the rare occasion where I had  a conflict with svn, it was very easy to solve manually by removing the conflict tags inserted by svn. With git, I never had a single conflict ;-) > Finally, it's pretty much a given that Git's manpages continue to use > AsciiDoc because there are few other things that can generate actual > manpages. I'm not sure it would be a good idea to keep half of Git's > documentation in one format and the rest in another. That's a good argument. My personal opinion is that users prefer to use '-help' for short help and to read the tutorial or the user guide for more in-depth information. I never use man personally... OK, that's probably because I use Windows :-) > And AsciiDoc is -- > by far! -- not the worst choice. I'm tempted to say it's the best that > I know. AsciiDoc is indeed excellent if you want to write in a plain text editor. But LyX is easier to use and more porwerful :-) Thanks, Abdel -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 In reply to this post by Abdelrazak Younes-2 You wrote: > Junio C Hamano wrote: > > > > How greppable and "log -p"-able is the documentation written in LyX? > > LyX format is plain text, loosely based on LateX. Here's attached a > sample .lyx file FYI. We have one tag per line and a maximum of 80 char > per line so that the format is easily parsable. Advanced users often use > unix tools (grep, sed, etc) to modify the .lyx file manually. Is it just me or is the format very hard to read?  For example, line 492ff spells a list of quoted items as     \begin_layout Standard     Generally, you would send email to [hidden email] to subscribe      to these lists or to [hidden email] to unsubscribe, where           \begin_inset Quotes eld     \end_inset     foo     \begin_inset Quotes erd     \end_inset      is one of     \begin_inset Quotes eld     \end_inset     announce     \begin_inset Quotes erd     \end_inset etc.  Of course I can "parse" the language, but my untrained eye is unable to fluently read the text hiding behind it. Also, if I made a commit changing the "announce", you would have to turn up diff context to at least 13 lines to get any _semantic_ context of the change. - Thomas signature.asc (204 bytes) Download Attachment
Open this post in threaded view
|

Re: markdown 2 man, was Re: Git Community Book

 Thomas Rast wrote: > You wrote: >     >> Junio C Hamano wrote: >>       >>> How greppable and "log -p"-able is the documentation written in LyX? >>>         >> LyX format is plain text, loosely based on LateX. Here's attached a >> sample .lyx file FYI. We have one tag per line and a maximum of 80 char >> per line so that the format is easily parsable. Advanced users often use >> unix tools (grep, sed, etc) to modify the .lyx file manually. >>       > > Is it just me or is the format very hard to read?  For example, line > 492ff spells a list of quoted items as >     Right, quote is a special case in lyx format because we have to take care of locale differences. So, as you guessed, quotes are not really written with the ascii quote character. But the format is not that hard in general. If needed, I could modify this special case so that it's easier to read though. Don't get me wrong, I don't pretend that LyX is easy to read for the untrained eyes, it is not. But simple modifications like Junio's example is definitely possible. For non simple text insertion, it is better to launch LyX and to type the modification within LyX. But maybe this is a showstopper for you, and so is maybe our treatment of quotes. In which case I'll stop arguying :-) Abdel. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html
 In reply to this post by Abdelrazak Younes-2 On Fri, Aug 1, 2008 at 11:50 AM, Abdelrazak Younes <[hidden email]> wrote: > > AsciiDoc is indeed excellent if you want to write in a plain text editor. > But LyX is easier to use and more porwerful :-) What is really powerful is TeX. As to LyX, it is leaky abstraction over it. I have never been able to use without ending up saying, it is so much easier and much more powerful to use Latex than trying to do the same with LyX. Of course, LyX looks much better nowadays than used to be, so I decided to give it another try, and here is my fifteen minutes experience with it. First, I tried to open FAQ.lyx that you attached to your previous email, and here is what I see: === /tmp/FAW.lix is from a different version of LyX, but the lex2lex script failed to covert it. === This is result was received with two LyX versions that I tried: LyX Version 1.4.3 (21/09/2006) LyX 1.5.5 (Sun, May 11, 2008) Now, I see, that your FAQ was created with LyX 1.6.0svn, which is not released yet. So, I hope that this issue will be correctly before it will be released. Otherwise, anyone opening document with 1.6.0 will make it unaccessible to users of previous versions. Then I tried to use Formatted reference and everything looks okay until I tried to generate DVI file, where I was welcome but the following error: === Paragraph ended before \@prettyref was complete. === What is \@prettyref? What is wrong with my paragraph? Actually, my paragraph is fine, it is just when you use Formatted reference, you should know that it is implemented using prettyref TeX package, which requires three letter prefix in name of each label. Why did not LyX warn me about that? BTW, is really prettyref is the best package for this job anyway? I remember some TeX experts recommended some other packages for references. Finally, I still have not figured out how to the same what AsciiDoc does: Chapter #, $CHAPTER_NAME It does not look like that LyX can produce references in this format. The I tried to insert some verbatim text, and I cannot find the standard way to do that in LyX. Sure, I can press CTRL-L and type in TeX: \begin{verbatim} # git itself (approx. 10MB download):$ git clone git://git.kernel.org/pub/scm/git/git.git         # the linux kernel (approx. 150MB download): $git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git \end{verbatim} but I don't think that having a lot TeX code is going to help us with having good formatted HTML version. BTW, it is really annoying to see TeX code displayed in proportional fonts and formatted with full adjustment. For instance, the last line was displayed like this:$                               git                              clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git Another rather surprising experience for those who got used to HTML: Left-click on a reference produces its properties, while the right click means to go to the label, and once you jump on it, there is no way to jump back (at least, I was not able to find how to do that). Well, I wrote all above only because I hope that LyX will continue to improve. It looks much better now than before. Yet, I will rather stay with plain text editors for now. Some of them are much more powerful than Notepad :) Dmitry -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html
 Hi Dimitry, Dmitry Potapov wrote: >  On Fri, Aug 1, 2008 at 11:50 AM, Abdelrazak Younes <[hidden email]> >  wrote: > > AsciiDoc is indeed excellent if you want to write in a plain text > > editor. But LyX is easier to use and more porwerful :-) > >  What is really powerful is TeX. As to LyX, it is leaky abstraction >  over it. I have never been able to use without ending up saying, it >  is so much easier and much more powerful to use Latex than trying to >  do the same with LyX. Of course, LyX looks much better nowadays than >  used to be, so I decided to give it another try, and here is my >  fifteen minutes experience with it. I was afraid this thread will turn into a pro and con of LyX versus plain LateX :-) >  First, I tried to open FAQ.lyx that you attached to your previous >  email, and here is what I see: ... >  Now, I see, that your FAQ was created with LyX 1.6.0svn, which is not >  released yet. So, I hope that this issue will be correctly before it >  will be released. Of course. Sorry, as I use the pre-release I didn't think that about that. FYI, we will release one last version of 1.5.x that is able to read 1.6 format. 1.6 will is of course able to read all previous format. >  Otherwise, anyone opening document with 1.6.0 will make it >  unaccessible to users of previous versions. > >  Then I tried to use Formatted reference and everything looks okay >  until I tried to generate DVI file, where I was welcome but the >  following error: === Paragraph ended before \@prettyref was >  complete. === > >  What is \@prettyref? What is wrong with my paragraph? Actually, my >  paragraph is fine, it is just when you use Formatted reference, you >  should know that it is implemented using prettyref TeX package, which >  requires three letter prefix in name of each label. Why did not LyX >  warn me about that? BTW, is really prettyref is the best package for >  this job anyway? I remember some TeX experts recommended some other >  packages for references. Aha, yes you're right. LyX will automatically insert those three letters (eg. 'cha' for chapter). This is the reason why I never came across this bug. We'll try to fix that, thanks! > >  Finally, I still have not figured out how to the same what AsciiDoc >  does: Chapter #, $CHAPTER_NAME It does not look like that LyX can > produce references in this format. You can choose among a number of document class. If you want the "Chapter" prefixing, choose the 'Book' document class. The default, document class is 'Article', for with you don't have level 1 sections. > The I tried to insert some verbatim text, and I cannot find the > standard way to do that in LyX. There are at least two: - The LyX-code environment - The listing inset The listing inset supports a number of languages so you'll be able to have syntax highlighting and cloring for your language of choice. > Sure, I can press CTRL-L and type in > TeX: \begin{verbatim} # git itself (approx. 10MB download):$ git >  clone git://git.kernel.org/pub/scm/git/git.git # the linux kernel >  (approx. 150MB download): $git clone > git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git > \end{verbatim} > > but I don't think that having a lot TeX code is going to help us > with having good formatted HTML version. No, either LyX-code (To choose from the Layout combo box) or preferable the Listing inset (Menu Insert -> Program Listing). Of course, all these action have keyboard shortcuts. > > BTW, it is really annoying to see TeX code displayed in proportional > fonts and formatted with full adjustment. For instance, the last > line was displayed like this: > >$                               git >  clone >  git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git Yes I know, this will be better in 1.6 due out this month in principle. >  Another rather surprising experience for those who got used to HTML: >  Left-click on a reference produces its properties, while the right >  click means to go to the label, and once you jump on it, there is no >  way to jump back (at least, I was not able to find how to do that). There is one 'Ctrl-0' but this is more or less hidden feature. 1.6 will have context menu so all the above actions will be a lot more consistant and easier. >  Well, I wrote all above only because I hope that LyX will continue >  to improve. It looks much better now than before. Thanks for the comments :-) >  Yet, I will rather >  stay with plain text editors for now. Some of them are much more >  powerful than Notepad :) It's a matter of choice. I have to confess that I don't use plain text editor anymore because I am so used to LyX keybindings. Thanks, Abdel. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [hidden email] More majordomo info at  http://vger.kernel.org/majordomo-info.html