You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by Gintautas Grigelionis <g....@gmail.com> on 2018/03/01 06:28:36 UTC
Ant documentation
I made an attempt to convert the manual to HTML 5, the rationale being that
HTML 5 deprecates tt tag and recommends to replace it with tags like code,
kbd, samp and var, which could be used in a more consistent way to achieve
something closer to a semantic markup.
I tried then to use the replacement tags as consistently as possible in
such a large body of text, but I realised that we perhaps need a kind of a
style guide. Would you like to discuss it? Where would it best fit in the
source code tree?
Gintas
Re: Ant documentation
Posted by Gintautas Grigelionis <g....@gmail.com>.
2018-03-02 13:13 GMT+01:00 Stefan Bodewig <bo...@apache.org>:
> > All I wanted to say, keeping things visually consistent helps
> > understanding. So, my simple set of rules is:
>
> > - <var> is for attributes
> > - <q> is for values
> > - <code> is for shell variable names/property name/CLI options and
> input
> > (should change that to <kbd>, really)
> > - <samp> is for everything else, like filenames etc
>
> Looks reasonable.
>
I added another batch of changes related to <kbd> which is used for input,
CLI options and external commands/utilities.
While doing that, I realised that <pre> needs both input and output classes
(the latter being already present).
My choice was to make <pre class="input"> and <kbd> visually identical,
somewhat reminiscent of old CRT terminals.
Then I added more highlighting for class and method names with <code
class="code">,
which is visually identical to <pre>, but used inline, and even some <code
class="output">.
You can see the result at
https://rawgit.com/apache/ant/master/manual/index.html
Gintas
Re: Ant documentation
Posted by Gintautas Grigelionis <g....@gmail.com>.
2018-03-02 13:13 GMT+01:00 Stefan Bodewig <bo...@apache.org>:
> On 2018-03-02, Gintautas Grigelionis wrote:
>
> > 2018-03-02 9:54 GMT+01:00 Stefan Bodewig <bo...@apache.org>:
>
> >> On 2018-03-01, Stefan Bodewig wrote:
>
> >>>> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
> >>>> g.grigelionis@gmail.com> wrote:
>
> >>>>> I tried then to use the replacement tags as consistently as
> >>>>> possible in such a large body of text, but I realised that we
> >>>>> perhaps need a kind of a style guide. Would you like to discuss
> >>>>> it? Where would it best fit in the source code tree?
>
> >>> I'm not convinced I want to have any kind of rules keep people from
> >>> writing docs :-)
>
> >> This comment isn't fair and I should have known better, sorry.
>
> > I didn't even notice your remark, really :-)
>
> That's good. Sometimes I realize when I'm being a jerk as in this case,
> often I don't (and I appreciate people telling me when that happens).
>
> > All I wanted to say, keeping things visually consistent helps
> > understanding. So, my simple set of rules is:
>
> > - <var> is for attributes
> > - <q> is for values
> > - <code> is for shell variable names/property name/CLI options and
> input
> > (should change that to <kbd>, really)
> > - <samp> is for everything else, like filenames etc
>
> Looks reasonable.
>
I feel a need to put this as a note somewhere in the manual. Also, target
attributes for hyperlinks must be reviewed, please see below for a snippet
of my browser dev console log :-(
Gintas
Mixed Content: The page at '<URL>' was loaded over HTTPS, but requested an
insecure resource '<URL>'. This content should also be served over HTTPS.
ide.html:1 Mixed Content: The page at 'https://rawgit.com/apache/
ant/master/manual/index.html' was loaded over HTTPS, but requested an
insecure resource 'http://jdee.sourceforge.net/'. This content should also
be served over HTTPS.
jdee.sourceforge.net/:8 Mixed Content: The page at '
https://rawgit.com/apache/ant/master/manual/index.html' was loaded over
HTTPS, but requested an insecure resource 'http://jdee.sourceforge.net/
toc.html'. This content should also be served over HTTPS.
jdee.sourceforge.net/:9 Mixed Content: The page at '
https://rawgit.com/apache/ant/master/manual/index.html' was loaded over
HTTPS, but requested an insecure resource 'http://jdee.sourceforge.net/
rootpage.html'. This content should also be served over HTTPS.
ide.html:1 Mixed Content: The page at 'https://rawgit.com/apache/
ant/master/manual/index.html' was loaded over HTTPS, but requested an
insecure resource 'http://ant.netbeans.org/'. This content should also be
served over HTTPS.
ide.html:1 Mixed Content: The page at 'https://rawgit.com/apache/
ant/master/manual/index.html' was loaded over HTTPS, but requested an
insecure resource 'http://ant.netbeans.org/'. This content should also be
served over HTTPS.
jdee.sourceforge.net/toc.html:63 Mixed Content: The page at '
https://rawgit.com/apache/ant/master/manual/index.html' was loaded over
HTTPS, but requested an insecure image 'http://jdee.sourceforge.net/
images/scoutsel.gif'. This content should also be served over HTTPS.
jdee.sourceforge.net/rootpage.html:17 Mixed Content: The page at '
https://rawgit.com/apache/ant/master/manual/index.html' was loaded over
HTTPS, but requested an insecure image 'http://jdee.sourceforge.net/
images/jdelogo.gif'. This content should also be served over HTTPS.
index.html:1 Refused to display 'https://www.jetbrains.com/idea/' in a
frame because it set 'X-Frame-Options' to 'deny'.
netbeans.org/projects/ant/ Failed to load resource: the server responded
with a status of 404 (Not Found)
data:,:1 Refused to display 'https://netbeans.org/projects/ant/' in a frame
because an ancestor violates the following Content Security Policy
directive: "frame-ancestors 'self'".
netbeans.org/projects/ant/ Failed to load resource: the server responded
with a status of 404 (Not Found)
data:,:1 Refused to display 'https://netbeans.org/projects/ant/' in a frame
because an ancestor violates the following Content Security Policy
directive: "frame-ancestors 'self'".
www.ibm.com/developerworks/offers/wsad2.html:1 Refused to apply style from '
https://www.ibm.com/us-en/' because its MIME type ('text/html') is not a
supported stylesheet MIME type, and strict MIME checking is enabled.
Re: Ant documentation
Posted by Stefan Bodewig <bo...@apache.org>.
On 2018-03-02, Gintautas Grigelionis wrote:
> 2018-03-02 9:54 GMT+01:00 Stefan Bodewig <bo...@apache.org>:
>> On 2018-03-01, Stefan Bodewig wrote:
>>>> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
>>>> g.grigelionis@gmail.com> wrote:
>>>>> I tried then to use the replacement tags as consistently as
>>>>> possible in such a large body of text, but I realised that we
>>>>> perhaps need a kind of a style guide. Would you like to discuss
>>>>> it? Where would it best fit in the source code tree?
>>> I'm not convinced I want to have any kind of rules keep people from
>>> writing docs :-)
>> This comment isn't fair and I should have known better, sorry.
> I didn't even notice your remark, really :-)
That's good. Sometimes I realize when I'm being a jerk as in this case,
often I don't (and I appreciate people telling me when that happens).
> All I wanted to say, keeping things visually consistent helps
> understanding. So, my simple set of rules is:
> - <var> is for attributes
> - <q> is for values
> - <code> is for shell variable names/property name/CLI options and input
> (should change that to <kbd>, really)
> - <samp> is for everything else, like filenames etc
Looks reasonable.
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant documentation
Posted by Gintautas Grigelionis <g....@gmail.com>.
2018-03-02 9:54 GMT+01:00 Stefan Bodewig <bo...@apache.org>:
> On 2018-03-01, Stefan Bodewig wrote:
>
> >> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
> >> g.grigelionis@gmail.com> wrote:
>
> >>> I tried then to use the replacement tags as consistently as possible in
> >>> such a large body of text, but I realised that we perhaps need a kind
> of a
> >>> style guide. Would you like to discuss it? Where would it best fit in
> the
> >>> source code tree?
>
> > I'm not convinced I want to have any kind of rules keep people from
> > writing docs :-)
>
> This comment isn't fair and I should have known better, sorry.
>
> Whenever people who are new to Open Source ask where to contribute I
> first point out that it is supposed to be fun and they should pick the
> thing they enjoy most.
>
> For most developers I know (including myself) writing documentation is
> not something they enjoy. It's a chore that needs to get done. Having a
> style guide can help or it can make things worse. If it provides a
> guideline that makes it easier to write proper documentation, then it
> probably is a welcome tool. What I wouldn't want to see is a set of
> rules that get enforced and may even prevent people from writing
> documentation - but I don't think this is what Gintas suggested.
>
> And of course there are the rare folks who actually enjoy writing
> docs. All power to them :-)
>
I didn't even notice your remark, really :-) All I wanted to say, keeping
things visually consistent helps understanding.
So, my simple set of rules is:
- <var> is for attributes
- <q> is for values
- <code> is for shell variable names/property name/CLI options and input
(should change that to <kbd>, really)
- <samp> is for everything else, like filenames etc
I was thinking of finding a suitable tag to overload in order to avoid
typing <code><...></code>;
but I'd settle for a CSS class and/or CSS selector for q as a child of code
(because it's a special case of quoting, really).
So, any opinions on that?
Gintas
P.S. I was having a beer tonight with a guy who told me that he liked
Gradle, but the documentation was lacking ;-)
Re: Ant documentation
Posted by Stefan Bodewig <bo...@apache.org>.
On 2018-03-01, Stefan Bodewig wrote:
>> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
>> g.grigelionis@gmail.com> wrote:
>>> I tried then to use the replacement tags as consistently as possible in
>>> such a large body of text, but I realised that we perhaps need a kind of a
>>> style guide. Would you like to discuss it? Where would it best fit in the
>>> source code tree?
> I'm not convinced I want to have any kind of rules keep people from
> writing docs :-)
This comment isn't fair and I should have known better, sorry.
Whenever people who are new to Open Source ask where to contribute I
first point out that it is supposed to be fun and they should pick the
thing they enjoy most.
For most developers I know (including myself) writing documentation is
not something they enjoy. It's a chore that needs to get done. Having a
style guide can help or it can make things worse. If it provides a
guideline that makes it easier to write proper documentation, then it
probably is a welcome tool. What I wouldn't want to see is a set of
rules that get enforced and may even prevent people from writing
documentation - but I don't think this is what Gintas suggested.
And of course there are the rare folks who actually enjoy writing
docs. All power to them :-)
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant documentation
Posted by Stefan Bodewig <bo...@apache.org>.
On 2018-03-01, Dominique Devienne wrote:
> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
> g.grigelionis@gmail.com> wrote:
>> I tried then to use the replacement tags as consistently as possible in
>> such a large body of text, but I realised that we perhaps need a kind of a
>> style guide. Would you like to discuss it? Where would it best fit in the
>> source code tree?
I'm not convinced I want to have any kind of rules keep people from
writing docs :-)
> Isn't the HTML manual generated? Sure it's checked-in, but I thought there
> was a generation process.
This site is generated, the manual is not. We once had experiments
creating the task manual pages via a doclet IIRC, but this never went
far enough to be used in practice. Adding all the stuff that is part of
the manual back into the classes would certainly require a lot of time,
which was one of the problems.
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant documentation
Posted by Gintautas Grigelionis <g....@gmail.com>.
2018-03-02 7:44 GMT+01:00 Jan Matèrne (jhm) <ap...@materne.de>:
> > > > > I made an attempt to convert the manual to HTML 5, the rationale
> > > > being
> > > > > that HTML 5 deprecates tt tag and recommends to replace it with
> > > > > tags like code, kbd, samp and var, which could be used in a more
> > > > consistent
> > > > > way to achieve something closer to a semantic markup.
> > > > >
> > > > > I tried then to use the replacement tags as consistently as
> > > > > possible in such a large body of text, but I realised that we
> > > > > perhaps need a kind of a style guide. Would you like to discuss
> > > > > it? Where would it best fit in the source code tree?
> > > > >
> > > >
> > > > Isn't the HTML manual generated? Sure it's checked-in, but I
> > thought
> > > > there was a generation process.
> > > > If that's the case (I may have dreamed it) then it's likely the
> > > > generator that needs fixing, not the build product. --DD
> > >
> > > No. There were some experiments and maybe some pages were generated
> > > during that experiment.
> > > But the manual is a manual work. (double manual ;)
> > > https://svn.apache.org/repos/asf/ant/sandbox/historical/xdocs/
> > >
> >
> > One may use xdoc and generate html with Doxia by calling its CLI.
> > However, Ant sorely lacks a site generator on par with Maven site
> > plugin.
>
> All generation requires a model to generate from.
> AFAIK the site-plugin uses the pom for this purpose.
> We don't have such a model in Ant.
> Also I can't remember a wish for that.
> Additionally I don't know any project (in my company) that uses these
> sites. Maybe
> they are useful for open source projects.
>
site plugin gets a lot of configuration from pom.xml, but there's site.xml,
too.
Perhaps if a wrapper of Doxia sitetools with a distinct skin would be used
if it were available?
Gintas
AW: Ant documentation
Posted by "Jan Matèrne (jhm)" <ap...@materne.de>.
> > > > I made an attempt to convert the manual to HTML 5, the rationale
> > > being
> > > > that HTML 5 deprecates tt tag and recommends to replace it with
> > > > tags like code, kbd, samp and var, which could be used in a more
> > > consistent
> > > > way to achieve something closer to a semantic markup.
> > > >
> > > > I tried then to use the replacement tags as consistently as
> > > > possible in such a large body of text, but I realised that we
> > > > perhaps need a kind of a style guide. Would you like to discuss
> > > > it? Where would it best fit in the source code tree?
> > > >
> > >
> > > Isn't the HTML manual generated? Sure it's checked-in, but I
> thought
> > > there was a generation process.
> > > If that's the case (I may have dreamed it) then it's likely the
> > > generator that needs fixing, not the build product. --DD
> >
> > No. There were some experiments and maybe some pages were generated
> > during that experiment.
> > But the manual is a manual work. (double manual ;)
> > https://svn.apache.org/repos/asf/ant/sandbox/historical/xdocs/
> >
>
> One may use xdoc and generate html with Doxia by calling its CLI.
> However, Ant sorely lacks a site generator on par with Maven site
> plugin.
All generation requires a model to generate from.
AFAIK the site-plugin uses the pom for this purpose.
We don't have such a model in Ant.
Also I can't remember a wish for that.
Additionally I don't know any project (in my company) that uses these sites. Maybe
they are useful for open source projects.
I don’t think that we should spend any effort into that.
But Ant is an OS project - if you want to do a prototype you're welcome.
Jan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant documentation
Posted by Gintautas Grigelionis <g....@gmail.com>.
2018-03-01 10:43 GMT+01:00 Jan Matèrne (jhm) <ap...@materne.de>:
> > > I made an attempt to convert the manual to HTML 5, the rationale
> > being
> > > that HTML 5 deprecates tt tag and recommends to replace it with tags
> > > like code, kbd, samp and var, which could be used in a more
> > consistent
> > > way to achieve something closer to a semantic markup.
> > >
> > > I tried then to use the replacement tags as consistently as possible
> > > in such a large body of text, but I realised that we perhaps need a
> > > kind of a style guide. Would you like to discuss it? Where would it
> > > best fit in the source code tree?
> > >
> >
> > Isn't the HTML manual generated? Sure it's checked-in, but I thought
> > there was a generation process.
> > If that's the case (I may have dreamed it) then it's likely the
> > generator that needs fixing, not the build product. --DD
>
> No. There were some experiments and maybe some pages were generated during
> that experiment.
> But the manual is a manual work. (double manual ;)
> https://svn.apache.org/repos/asf/ant/sandbox/historical/xdocs/
>
One may use xdoc and generate html with Doxia by calling its CLI. However,
Ant sorely lacks a site generator on par with Maven site plugin.
Gintas
AW: Ant documentation
Posted by "Jan Matèrne (jhm)" <ap...@materne.de>.
> > I made an attempt to convert the manual to HTML 5, the rationale
> being
> > that HTML 5 deprecates tt tag and recommends to replace it with tags
> > like code, kbd, samp and var, which could be used in a more
> consistent
> > way to achieve something closer to a semantic markup.
> >
> > I tried then to use the replacement tags as consistently as possible
> > in such a large body of text, but I realised that we perhaps need a
> > kind of a style guide. Would you like to discuss it? Where would it
> > best fit in the source code tree?
> >
>
> Isn't the HTML manual generated? Sure it's checked-in, but I thought
> there was a generation process.
> If that's the case (I may have dreamed it) then it's likely the
> generator that needs fixing, not the build product. --DD
No. There were some experiments and maybe some pages were generated during that experiment.
But the manual is a manual work. (double manual ;)
https://svn.apache.org/repos/asf/ant/sandbox/historical/xdocs/
Jan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant documentation
Posted by Dominique Devienne <dd...@gmail.com>.
On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
g.grigelionis@gmail.com> wrote:
> I made an attempt to convert the manual to HTML 5, the rationale being that
> HTML 5 deprecates tt tag and recommends to replace it with tags like code,
> kbd, samp and var, which could be used in a more consistent way to achieve
> something closer to a semantic markup.
>
> I tried then to use the replacement tags as consistently as possible in
> such a large body of text, but I realised that we perhaps need a kind of a
> style guide. Would you like to discuss it? Where would it best fit in the
> source code tree?
>
Isn't the HTML manual generated? Sure it's checked-in, but I thought there
was a generation process.
If that's the case (I may have dreamed it) then it's likely the generator
that needs fixing, not the build product. --DD