Ant documentation

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Ant documentation

Gintautas Grigelionis
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
Reply | Threaded
Open this post in threaded view
|

Re: Ant documentation

Dominique Devienne-2
On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Ant documentation

Stefan Bodewig
On 2018-03-01, Dominique Devienne wrote:

> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
> [hidden email]> 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

AW: Ant documentation

Jan Matèrne (jhm)
In reply to this post by Dominique Devienne-2
> > 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Ant documentation

Gintautas Grigelionis
2018-03-01 10:43 GMT+01:00 Jan Matèrne (jhm) <[hidden email]>:

> > > 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
Reply | Threaded
Open this post in threaded view
|

AW: Ant documentation

Jan Matèrne (jhm)
> > > > 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Ant documentation

Gintautas Grigelionis
2018-03-02 7:44 GMT+01:00 Jan Matèrne (jhm) <[hidden email]>:

> > > > > 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
Reply | Threaded
Open this post in threaded view
|

Re: Ant documentation

Stefan Bodewig
In reply to this post by Stefan Bodewig
On 2018-03-01, Stefan Bodewig wrote:

>> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
>> [hidden email]> 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Ant documentation

Gintautas Grigelionis
2018-03-02 9:54 GMT+01:00 Stefan Bodewig <[hidden email]>:

> On 2018-03-01, Stefan Bodewig wrote:
>
> >> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
> >> [hidden email]> 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>&lt;...&gt;</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 ;-)
Reply | Threaded
Open this post in threaded view
|

Re: Ant documentation

Stefan Bodewig
On 2018-03-02, Gintautas Grigelionis wrote:

> 2018-03-02 9:54 GMT+01:00 Stefan Bodewig <[hidden email]>:

>> On 2018-03-01, Stefan Bodewig wrote:

>>>> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
>>>> [hidden email]> 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Ant documentation

Gintautas Grigelionis
2018-03-02 13:13 GMT+01:00 Stefan Bodewig <[hidden email]>:

> On 2018-03-02, Gintautas Grigelionis wrote:
>
> > 2018-03-02 9:54 GMT+01:00 Stefan Bodewig <[hidden email]>:
>
> >> On 2018-03-01, Stefan Bodewig wrote:
>
> >>>> On Thu, Mar 1, 2018 at 7:28 AM, Gintautas Grigelionis <
> >>>> [hidden email]> 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.
Reply | Threaded
Open this post in threaded view
|

Re: Ant documentation

Gintautas Grigelionis
In reply to this post by Stefan Bodewig
2018-03-02 13:13 GMT+01:00 Stefan Bodewig <[hidden email]>:

> > 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