maven-doxia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Lukas Theussl <ltheu...@apache.org>
Subject Re: svn commit: r657299 - in /maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src: main/java/org/apache/maven/doxia/module/apt/ test/java/org/apache/maven/doxia/module/apt/
Date Sun, 18 May 2008 19:39:39 GMT

Hi Dennis,

For single-document transformations, I think it's true: a string with a 
'/' is always an external link. However, for sinks that aggregate 
several source documents into one output file (eg the FoAggregateSink 
used by the pdf plugin), an 'external' link (like 
'./reference/index.html') may become an internal link. I have tried to 
take that into account by introducing the additional notion of a 'local' 
link, as defined in DoxiaUtils.java, but this probably needs some more 
thinking.

Note that there is really only a problem with the APT format, it is 
really unfortunate that there is no special designation for internal 
links (a '#'), because it is hard to define the opposite. The original 
APT guide defined very clearly (but arbitrarily) what was an external 
link ("http:/", "https:/", etc) but in practice this is awkward and not 
sufficient. Maybe we should reconsider the original proposal at DOXIA-208?

-Lukas


Dennis Lundberg wrote:
> Lukas, Ive been thinking about another possible case for 
> isExternalLink(String).
> 
> Shouldn't a String that contains the character '/' always be considered 
> an external link?
> 
> '/' is not a valid character in an anchor, so we could make use of that 
> fact.
> 
> It would improve the backwards compatibility a bit.
> 
> ltheussl@apache.org wrote:
> 
>> Author: ltheussl
>> Date: Sat May 17 00:01:52 2008
>> New Revision: 657299
>>
>> URL: http://svn.apache.org/viewvc?rev=657299&view=rev
>> Log:
>> [DOXIA-208] Adapt link/anchor handling in apt module.
>>
>> Modified:
>>     
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptParser.java

>>
>>     
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java

>>
>>     
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptUtils.java

>>
>>     
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptParserTest.java

>>
>>     
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptSinkTest.java

>>
>>
>> Modified: 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptParser.java

>>
>> URL: 
>> http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptParser.java?rev=657299&r1=657298&r2=657299&view=diff

>>
>> ============================================================================== 
>>
>> --- 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptParser.java

>> (original)
>> +++ 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptParser.java

>> Sat May 17 00:01:52 2008
>> @@ -462,13 +462,7 @@
>>  
>>                              String linkAnchor = getTraversedAnchor( 
>> text, i + 1, end );
>>  
>> -                            if ( !DoxiaUtils.isValidId( linkAnchor ) )
>> -                            {
>> -                                // debug only: anchors in apt may 
>> contain spaces
>> -                                getLog().debug( "Modified anchor 
>> name: " + linkAnchor );
>> -
>> -                                linkAnchor = DoxiaUtils.encodeId( 
>> linkAnchor );
>> -                            }
>> +                            linkAnchor = AptUtils.encodeAnchor( 
>> linkAnchor );
>>  
>>                              sink.anchor( linkAnchor );
>>                          }
>>
>> Modified: 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java

>>
>> URL: 
>> http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java?rev=657299&r1=657298&r2=657299&view=diff

>>
>> ============================================================================== 
>>
>> --- 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java

>> (original)
>> +++ 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java

>> Sat May 17 00:01:52 2008
>> @@ -24,6 +24,7 @@
>>  import java.util.Stack;
>>  
>>  import org.apache.maven.doxia.sink.AbstractTextSink;
>> +
>>  import org.codehaus.plexus.util.StringUtils;
>>  
>>  /**
>> @@ -725,7 +726,7 @@
>>          if ( !headerFlag )
>>          {
>>              write( LINK_START_1_MARKUP );
>> -            text( name );
>> +            text( name.startsWith( "#" ) ? name.substring( 1 ) : name );
>>              write( LINK_START_2_MARKUP );
>>          }
>>      }
>>
>> Modified: 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptUtils.java

>>
>> URL: 
>> http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptUtils.java?rev=657299&r1=657298&r2=657299&view=diff

>>
>> ============================================================================== 
>>
>> --- 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptUtils.java

>> (original)
>> +++ 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptUtils.java

>> Sat May 17 00:01:52 2008
>> @@ -57,9 +57,9 @@
>>       * ie is not a link within the same document.
>>       *
>>       * @param link The link to check.
>> -     * @return True if the link (ignoring case) starts with either of 
>> the
>> -     * following: "http:/", "https:/", "ftp:/", "mailto:", "file:/",
>> -     * "../" or "./". Note that Windows style separators "\" are not 
>> allowed
>> +     * @return True if the link (ignoring case) starts with either 
>> "http:/",
>> +     * "https:/", "ftp:/", "mailto:", "file:/", "../", "./" or 
>> contains the
>> +     * string "://". Note that Windows style separators "\" are not 
>> allowed
>>       * for URIs, see  http://www.ietf.org/rfc/rfc2396.txt , section 
>> 2.4.3.
>>       */
>>      public static boolean isExternalLink( String link )
>> @@ -69,7 +69,7 @@
>>          return ( text.indexOf( "http:/" ) == 0 || text.indexOf( 
>> "https:/" ) == 0
>>              || text.indexOf( "ftp:/" ) == 0 || text.indexOf( 
>> "mailto:" ) == 0
>>              || text.indexOf( "file:/" ) == 0 || text.indexOf( "../" ) 
>> == 0
>> -            || text.indexOf( "./" ) == 0 );
>> +            || text.indexOf( "./" ) == 0 || text.indexOf( "://" ) != 
>> -1 );
>>      }
>>  
>>      /**
>> @@ -79,6 +79,9 @@
>>       *
>>       * @param text The text to transform.
>>       * @return The text with all non-LetterOrDigit characters removed.
>> +     * @deprecated This method was used for the original apt format, 
>> which
>> +     * removed all non alphanumeric characters from anchors.
>> +     * Use {@link #encodeAnchor(String)} instead.
>>       */
>>      public static String linkToKey( String text )
>>      {
>> @@ -97,6 +100,57 @@
>>          return buffer.toString();
>>      }
>>  
>> +    /**
>> +     * Construct a valid anchor. This is a simplified version of
>> +     * {@link org.apache.maven.doxia.util.DoxiaUtils#encodeId(String)}
>> +     * to ensure the anchor is a valid Doxia id.
>> +     * The procedure is identical to the one in
>> +     * {@link org.apache.maven.doxia.util.HtmlTools#encodeId(String)}:
>> +     *
>> +     * <ol>
>> +     *   <li> Trim the id</li>
>> +     *   <li> If the first character is not a letter, prepend the 
>> letter 'a'</li>
>> +     *   <li> Any space is replaced with an underscore '_'</li>
>> +     *   <li> Remove any non alphanumeric characters  except ':', 
>> '_', '.', '-'.</li>
>> +     * </ol>
>> +     *
>> +     * @param id The id to be encoded.
>> +     * @return The trimmed and encoded id, or null if id is null.
>> +     */
>> +    public static String encodeAnchor( String id )
>> +    {
>> +        if ( id == null )
>> +        {
>> +            return null;
>> +        }
>> +
>> +        id = id.trim();
>> +
>> +        int length = id.length();
>> +        StringBuffer buffer = new StringBuffer( length );
>> +
>> +        for ( int i = 0; i < length; ++i )
>> +        {
>> +            char c = id.charAt( i );
>> +
>> +            if ( ( i == 0 ) && ( !Character.isLetter( c ) ) )
>> +            {
>> +                buffer.append( 'a' );
>> +            }
>> +
>> +            if ( c == ' ' )
>> +            {
>> +                buffer.append( '_' );
>> +            }
>> +            else if ( ( Character.isLetterOrDigit( c ) ) || ( c == 
>> '-' ) || ( c == '_' ) || ( c == ':' ) || ( c == '.' ) )
>> +            {
>> +                buffer.append( c );
>> +            }
>> +        }
>> +
>> +        return buffer.toString();
>> +    }
>> +
>>      private AptUtils() {
>>          // utility class
>>      }
>>
>> Modified: 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptParserTest.java

>>
>> URL: 
>> http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptParserTest.java?rev=657299&r1=657298&r2=657299&view=diff

>>
>> ============================================================================== 
>>
>> --- 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptParserTest.java

>> (original)
>> +++ 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptParserTest.java

>> Sat May 17 00:01:52 2008
>> @@ -119,8 +119,8 @@
>>              createParser().parse( reader, sink );
>>  
>>              // No section, only subsection 1 and 2
>> -            assertTrue( output.toString().indexOf( "* 
>> {{{#SubSection_1}SubSection 1}}" ) != -1 );
>> -            assertTrue( output.toString().indexOf( "* 
>> {{{#SubSection_1211}SubSection 1211}}" ) == -1 );
>> +            assertTrue( output.toString().indexOf( "* 
>> {{{SubSection_1}SubSection 1}}" ) != -1 );
>> +            assertTrue( output.toString().indexOf( "* 
>> {{{SubSection_1211}SubSection 1211}}" ) == -1 );
>>          }
>>          finally
>>          {
>>
>> Modified: 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptSinkTest.java

>>
>> URL: 
>> http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptSinkTest.java?rev=657299&r1=657298&r2=657299&view=diff

>>
>> ============================================================================== 
>>
>> --- 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptSinkTest.java

>> (original)
>> +++ 
>> maven/doxia/doxia/trunk/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptSinkTest.java

>> Sat May 17 00:01:52 2008
>> @@ -185,7 +185,8 @@
>>      /** {@inheritDoc} */
>>      protected String getLinkBlock( String link, String text )
>>      {
>> -        return AptMarkup.LINK_START_1_MARKUP + link + 
>> AptMarkup.LINK_START_2_MARKUP + text + AptMarkup.LINK_END_MARKUP;
>> +        String lnk = link.startsWith( "#" ) ? link.substring( 1 ) : 
>> link;
>> +        return AptMarkup.LINK_START_1_MARKUP + lnk + 
>> AptMarkup.LINK_START_2_MARKUP + text + AptMarkup.LINK_END_MARKUP;
>>      }
>>  
>>      /** {@inheritDoc} */
>>
>>
>>
> 
> 

Mime
View raw message