From: Junio C Hamano <hidden> Date: 2016-06-15 22:45:05
Johannes Schindelin [off-list ref] writes:
Note also that Markdown cannot create TOCs automatically, AFAICT. So
probably it would be not all that easy to convert the User Manual to that
format.
The use of markdown may mean updates to the User Manual won't be merged
back to his book without effort and manual porting on his side, and the
side porting in the other direction has the same issue as well, but the
contents and the way materials are presented will be vastly different in
future versions anyway; not being able to side-port new material verbatim
may not be an issue. Discussion with Scott seems to suggest that the
overall philosophy of his book is "this is a different book targetted for
different audiences; its initial text happens to heavily borrow from the
existing documents but expected to become vastly improved", in other
words, fork-and-never-return.
That's one valid approach. I or you might have taken a different avenue,
but after all, it's his book, not mine, not yours, nor git list's book.
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.
We originally hoped (well, at least I did) that Scott's effort on his book
might help us in improving the User Manual as well, but the approach seems
to make it unlikely. But that is nothing to hold against him --- he is
doing his own thing in a way he feels is the best, and that's perfectly
fine. We lost nothing, perhaps except for a chance to cooperate a bit
better and to widen the community.
If at all, I would have preferred a format switch to Wiki syntax so that
we can use the same source on the Git wiki as in our Documentation/
directory.
Yeah, that's also true. I seem to recall markdown was used in ikiwiki?
El 30/7/2008, a las 21:32, Junio C Hamano escribió:
That's one valid approach. I or you might have taken a different
avenue,
but after all, it's his book, not mine, not yours, nor git list's
book.
Funnily enough, he chose to title it the "Git Community Book". Hard to
match Scott's enthusiasm; this is the second major initiative we've
seen from him in the last few days (the other being git-scm.com
itself) which to the casual onlooker might look like the "official"
Git homepage and documentation, but in both cases development occurred
behind the scenes and the list was only notified after the fact.
Better late than never I suppose.
We originally hoped (well, at least I did) that Scott's effort on
his book
might help us in improving the User Manual as well, but the approach
seems
to make it unlikely. But that is nothing to hold against him --- he
is
doing his own thing in a way he feels is the best, and that's
perfectly
fine. We lost nothing, perhaps except for a chance to cooperate a bit
better and to widen the community.
Even though there might not be an automated way to get changes back
from the fork, if there are clear improvements made then there is at
least no legal obstacle to incorporating them back in, the only
obstacle would be time and willingness to do so manually.
From: Scott Chacon <hidden> Date: 2016-06-15 22:45:05
On Wed, Jul 30, 2008 at 4:48 PM, Wincent Colaiuta [off-list ref] wrote:
El 30/7/2008, a las 21:32, Junio C Hamano escribió:
quoted
That's one valid approach. I or you might have taken a different avenue,
but after all, it's his book, not mine, not yours, nor git list's book.
Funnily enough, he chose to title it the "Git Community Book". Hard to match
Scott's enthusiasm; this is the second major initiative we've seen from him
in the last few days (the other being git-scm.com itself) which to the
casual onlooker might look like the "official" Git homepage and
documentation, but in both cases development occurred behind the scenes and
the list was only notified after the fact. Better late than never I suppose.
Not sure what else I could have done - I announced that I was starting
a documentation project like this about a week ago on this list, then
I started the book 3 days ago
(http://github.com/schacon/gitscm/commits/book) and announced it here
for initial review yesterday. I haven't told very many people about
it yet and I haven't linked to it from git-scm.com yet either. It's
been open source from the first minute on GitHub, and the link to the
source was on the website I posted here.
Same for the git-scm site - I started it on the 23rd and emailed Pasky
about it the next day, and the day after that he began submitting
patches to me for it and I announced it on this list. Am I missing
something here? Do you think I've been working on these secretly for
months, or something? If there is a better communication workflow, I
would be happy to do so.
I appreciate that you notice my enthusiasm, though. :)
Scott
quoted
We originally hoped (well, at least I did) that Scott's effort on his book
might help us in improving the User Manual as well, but the approach seems
to make it unlikely. But that is nothing to hold against him --- he is
doing his own thing in a way he feels is the best, and that's perfectly
fine. We lost nothing, perhaps except for a chance to cooperate a bit
better and to widen the community.
Even though there might not be an automated way to get changes back from the
fork, if there are clear improvements made then there is at least no legal
obstacle to incorporating them back in, the only obstacle would be time and
willingness to do so manually.
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.
From: Stephan Beyer <hidden> Date: 2016-06-15 22:45:05
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.txt
I think, this is easier than LyX for users and developers..
Regards,
Stephan
--
Stephan Beyer [off-list ref], PGP 0x6EDDD207FCC5040F
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.
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.
On Thu, Jul 31, 2008 at 04:33:24PM +0200, Abdelrazak Younes [off-list ref] 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.
On Thu, Jul 31, 2008 at 04:33:24PM +0200, Abdelrazak Younes[off-list ref] wrote:
quoted
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.html
Thanks for answering :-)
Abdel.
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.html
Last time I checked it was actually broken, but dblatex can transform
asciidoc's docbook output to latex, if that's really wished.
From: Jan Krüger <hidden> Date: 2016-06-15 22:45:05
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
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
On Fri, Aug 1, 2008 at 11:50 AM, Abdelrazak Younes [off-list ref] 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
On Fri, Aug 1, 2008 at 11:50 AM, Abdelrazak Younes [off-list ref]
wrote:
quoted
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.